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Introduction 




Am lthough Adobe AIR is a still new product release, it's already proving 
¥ w to be one of those technologies that is changing the rules of the game. 
Until AIR was introduced, the runtime environments of the desktop and Web 
were cleanly divided and clearly distinct from each other. Sure, you had Web- 
enabled desktop apps and technologies, such as Google Gears, that allowed 
Web apps some local capabilities. But by and large, the desktop was a stuffy 
world inhabited by the C++ and Objective-C programmers. 

Enter Adobe AIR. It has become a breath of fresh air to Web developers. For 
the first time, developers can now use Web technologies — such as HTML, 
JavaScript, Flash, or Flex — to create rich Internet applications (RIAs) that 
run on desktops and across multiple operating systems. These apps need not 
be mere "widgets" or "applets" but can be full-fledged, professional, and per- 
haps even "air-cooled" applications. 



Adobe AIR For Dummies serves as your friendly, no-nonsense guide to design- 
ing and developing Adobe AIR applications. Throughout the book, I focus on 
covering the essentials you need to successfully deploy your own AIR appli- 
cations. Using this book, you can 

f Get a solid understanding of the Adobe AIR API 

i*" Build AIR apps in three different ways: HTML/Ajax, Flex, and Flash 

V Design apps using HTML and CSS 

v 0 Work with local file systems and databases 

v 0 Make sense of application sandboxing and security 

You can create Adobe AIR apps using standard Web technologies (HTML, 
CSS, JavaScript, and Ajax), Flex, or Flash. It would take a book three times as 
thick as this one to fully cover AIR development equally across these tech- 
nologies. Consequently, although I give some coverage to Flex and Flash, 
the book focuses primarily on HTML, CSS, JavaScript, and Ajax. However, 
because the AIR runtime environment is independent of technologies used to 
develop the app, Flex and Flash developers can also able to follow along to 
better their understanding of AIR. You can find source code for many of this 
book's examples atwww.dummies.com/go/adobeairfd. 
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AIR For Dummies, I don't expect you to have any previous experi- 
ence with Adobe AIR, Flex Builder, or Flash. I do, however, assume that you 
have at least a working knowledge of HTML, CSS, JavaScript, and Ajax. Oh, 
yeah, I also assume that you understand the word arroyo. (Not that I talk 
about a deep gully, mind you.) 



Contentions Used in This Book 

Keep in mind the following conventions, or typographical rules, which I use 
throughout the book: 

Text formatting: I italicize new terms that I define. Bold text is used to 
indicate specific commands that you are to perform. Source code and 
URLs stand out from normal text with a monospaced font. 

Markup terminology: When working with Adobe AIR, you often work 
with markup style languages, including Hypertext Markup Language 
(HTML) and Extensible Markup Language (XML). A markup language 
consists of many elements (also called fags), each of which has a start 



tag, end tag, and 


content in between. For 


example: 




<hl>Are you 


an AIRhead?</hl> 







The <hl> is the start tag, </hl> is the end tag, and Are you an 
AiRhead? is the content. The entire piece of code is called the hi element 
or tag. 



What \!ou Don't Hatfe to Read 

Before you begin the book, let me point out a couple of "optional" modules 
that you can feel free to avoid without missing the information you absolutely 
need to know: 

^ Text marked with a Technical Stuff icon: Paragraphs with this icon 
beside them let you know that this "techie" material provides additional 
details to round out your understanding. But it is not required reading. 

V Sidebars: Once or twice, I stick some info in a shaded sidebar, which 
gives you some "ancillary info" but isn't critical to your understanding of 
the chapter. 
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Ik is carved up neatly and cleanly into four distinct parts, like so: 



Part 1: Airing It Out With Adobe AlR 

You begin soaring with AIR after you read Part I. In this part, discover the 
essentials of the AIR runtime environment and its Web-based framework. 
Adobe AIR apps can be created using three different Web technologies — 
standard HTML and Ajax, Flex, and Flash. In this section, I also show you how 
you can use each of these to build AIR apps. Even if you're familiar with just 
one of these technologies, you can still find it helpful to work with the other 
development environments because each has certain advantages and disad- 
vantages over the other. 



Part 11: AlR Application Design 

In Part II, you begin to get deeper into the design of AIR applications using 
HTML and JavaScript. You will explore how to create HTML/CSS-based user 
interfaces and add native operating system windows, menus, and icons. 

Part 111: Programming the Adobe AlR API 

Part III is the heart of the book. It is where you discover all aspects of the 
AIR API. You explore how to interact with the operating system and the file 
system. If you're developing a database application, this is where you can 
find out how to work with both local and remote databases. This part also 
covers deploying your app. 



Part IV: The Part of Tens 

Part IV is the traditional close to every For Dummies book — The Part of 
Tens. In this action-packed part, you explore ten strategies for security and 
sandboxing of your application, followed by ten tips to keep in mind for suc- 
cessful AIR debugging. Finally, I close out the book with a survey of ten killer 
RIAs. 
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ies books aren't content with just plain, ordinary pages with ordi- 
nary paragraphs. No, we like to make things more interesting and helpful by 
providing a few icons to point out material of special interest. These are the 
following 

The Remember icon indicates a paragraph that is particularly significant to 
your understanding of Adobe AIR development. 



The Tip icon points out key development tips and techniques that you want to 
be sure and take note of. 



The Warning icon acts as your early warning system, alerting you to potential 
pitfalls that you may encounter along the way. 



As I mention in the "What You Don't Have to Read" section, the Technical Stuff 
icon points out technical but not required info. 

Where to Go from Here 

Although you can read this book from cover to cover like a John Grisham novel, 
it's structured so that you don't have to. Here's a roadmap that will get you going 
to exactly where you want to go: 

v 0 To explore Adobe AIR and its components, turn the page over and begin 
reading Chapters 1. 

To create your first Adobe AIR application using HTML, skip over to 
Chapter 2. 

j> If you're a Flex or Flash developer, you may want to begin with Chapter 3. 

To dive head first into AIR app design, head over to Part II. 

V To explore the local file and database storage capabilities of AIR, read 
Chapters 10 and 11. 
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In this part . . . 

n 

#«^erhaps you're a Web developer and the idea of the 
V desktop environment of Adobe AIR seems foreign. Or 
perhaps you're a desktop programmer but are unfamiliar 
with Web technologies such as Ajax, Flex, or Flash. If so, 
then start here. You explore the Adobe AIR environment 
and the structure of an AIR application. Finally, you roll 
up your sleeves and develop your first AIR app. 













Chapter 1 

Started with Adobe AIR 



In This Chapter 

Understanding exactly what Adobe AIR is 
Discovering the significance of a new acronym — RIA 
Exploring the AIR security and signing model 
Setting up your development environment for Adobe AIR 



M/My eb developers, unite! For all too long, Web developers have been 
WW oppressed by the shackles of the browser window, their creativity 
stifled by cross-browser compatibility issues, their self-image hurt by the 
scoffs of desktop app programmers who trivialize browser-based solutions. . . 

But that was then; this is now. Or, to mimic the voiceover from an overly dra- 
matic movie trailer, Everything you know about Web development is about to 
change. Introducing Adobe AIR. . . 

Adobe AIR promises to liberate developers from the snares, toils, and 
oppression of their browser-based prisons and enable them to create "rich 
Internet applications" (RIAs) for the desktop. In true Braveheart fashion, 
maybe you will find yourself shouting from your office or cubicle, "You can 
take my life, but you can never take my Adobe AIR!" 

Okay, perhaps I am guilty of being just a wee bit over-the-top as I introduce 
Adobe AIR, but I hope the melodrama does serve a purpose. It helps show 
you that AIR really is not just another flavor of the week. AIR really does pro- 
vide a greater freedom to do things that HTML/Ajax, Flash, and Flex develop- 
ers can't do inside the browser. 

In this chapter, I introduce you to this "breath of fresh AIR" and get you 
started working with it. Viva la RIAs! 
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R enables Web developers to create cross-platform desktop applica- 
tions using and combining familiar Web technologies that they are already 
skilled in — such as HTML, JavaScript, Ajax, Flash, and Flex. 

Even though the technologies used to create it are Web based, an AIR appli- 
cation looks and feels like a normal Windows or Mac OS X program. It runs 
in its own window, has its own icon, and integrates with the menu system 
or taskbar. And it generally has the performance you would expect from a 
native operating system application. In fact, users will interact with an AIR 
app (see Figure 1-1) just the same as they do with any other application on 
their desktop. 



Creating Intemet-saWy apps 

An AIR application is technically not standalone. It is actually "powered by" 
the Adobe AIR runtime that must be installed on any computer in order to 
run the application. Therefore, when an AIR app is launched, the AIR runtime 
is automatically loaded behind the scenes prior to the loading of the app. 



Figure 1-1: 

Analytics 
Reporting 
Suite 
delivers a 
traditional 
Web appli- 
cation to the 
desktop. 
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When you create an AIR application, you build the app using Adobe Dreamweaver, 
Adobe Flex, Adobe Flash, or any text editor. (In Chapter 2, 1 show you how to 
basic HTML-based app in a text editor and Dreamweaver. Chapter 3 
u how to create a basic app in Flex and Flash.) 



As you can see, many parts of the application use Web techniques and tech- 
nologies that you're already used to working with. However, core to Adobe 
AIR is an application programming interface (API) that you can tap into to do 
real "desktop stuff," such as get access to local files, open native UI windows, 
create menus, and so on. I walk you through the API in Chapter 4. 

As you begin to explore the AIR API, you will see that the key strength of 
Adobe AIR is not in creating word processors or spreadsheets (although you 
can), but rather in enabling Web developers to shed the browser and safely 
deploy Internet-sawy apps onto the desktop. 

An AIR application is easily delivered to users with a single downloadable 
installer (which has an . air extension) regardless of the operating system. 
(See Chapter 14 for more on deployment.) 

Developers can create Internet-based desktop apps to some extent through 
widgets and Java, but both of these technologies have restrictions or limita- 
tions that have kept them as niche players. Widgets are intended for limited 
single screen, display-oriented purposes (such as a stock ticker). Cross- 
platform applications using Java runtime have traditionally suffered in com- 
parison to native OS apps — in terms of both performance and "look and 
feel" issues. Also, both widgets and Java apps are much weaker in working 
with rich media than Flash has been. 

In fact, you may want to jump over to Chapter 16 to take a quick look at ten 
great AIR applications that help demonstrate the power of the platform. 



Peeking inside Adobe A\R runtime 

The Adobe AIR runtime may be a relatively new platform, but it actually 
embeds three highly mature and stable cross-platform technologies to power 
AIR applications. These are the following: 

WebKit: Used for rendering HTML content inside an AIR app. WebKit is 
an open source, cross-platform browser and is the underlying rendering 
engine on which Apple's Safari browser is built. 

WebKit is known for its strong support of W3C standards, such as HTML, 
XHTML, Document Object Model (DOM), Cascading Style Sheets (CSS), 
and ECMAScript. However, it also provides support for enhanced func- 
tionality — enabling the creation of cool stuff such as rounded corners 
using CSS. Because you're developing solely for WebKit and not for every 
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browser under the sun, you're free to take advantage of these nonstan- 
dard extensions. 

more info on WebKit, go to www. webkit . org. 

V Adobe Flash Player: Used for playing Flash media (SWF files). Flash 
Player is a cross-platform virtual machine used to run media created in 
the Adobe Flash authoring environment and full SWF-based applications 
created using Adobe Flex. Flash Player has an embedded JavaScript-like 
scripting language called ActionScript 3. 

Inside your app, you can access existing Flash Player API calls as well as 
some enhanced functionality for vector-based drawing, multimedia sup- 
port (see Chapter 13), and a full networking stack (see Chapter 12). 

v 0 SQLite: A database engine for enabling local database access. It's an 
extremely lightweight, open source, cross-platform SQL database engine 
that is embedded in many desktop and mobile products. In contrast to 
most SQL databases, it doesn't require a separate server process, and it 
uses a standard file to store an entire database (tables, indexes, and so 
on). If you'd like to explore how to work with SQLite to create database 
apps, see Chapter 11. 

For more info on SQLite, go to www . sql i te . org. 
Figure 1-2 shows an overview of the AIR runtime architecture. 
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WebKit 



Flash Player 



Figure 1-2: 

Simplistic 
view of 
Adobe AIR 
runtime. 
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Having Flash Player and the WebKit rendering engine integrated inside AIR so 
tightly opens many possibilities for AIR developers. An AIR app can consist of 
several different possibilities: 



V HTML/JavaScript only 
v» HTML and Ajax 

Flash only 
y* Flex only 
f Flash/Flex and HTML 



In fact, AIR blurs the lines between Flash media, a Flex app, and a traditional 
HTML-based app. In many cases, an AIR application can be a combination of 
all these. Consider how these technologies can speak to each other: 

V You can access the Flash Player and ActionScript Library APIs from 
within JavaScript. (See Chapter 5 for more details.) 

ActionScript inside Flash can call JavaScript and access and modify the 
HTML DOM. (See Chapter 5.) 

W You can register JavaScript and ActionScript events anywhere — in 
Flash, Flex, or JavaScript. (You can thumb over to Chapter 6 to dive fully 
into events.) 




Because an AIR app can use all these technologies interchangeably, you can 
see that Adobe AIR breaks down the traditional walls that have existed in Web 
development architecture. 



Understanding the AlK Security Model 

One of the concepts that is important for you to understand from the get-go 
is application security. Desktop apps get permission in terms of what they 
can do and cannot do from the OS and the available permissions of the cur- 
rently logged-in user. They receive this level of access because the user 
needs to explicitly install the app — effectively telling the computer that the 
user trusts the app he or she is about to launch. As a result, native apps have 
access to read and write to the local file system and perform other typical 
desktop functions. 
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Web apps, however, are far more restrictive because of the potentially mali- 
cious nature of scripting. Consequently, Web apps limit all local file access, 
irm web-based actions only inside the context of a browser, and 
ata access to a single domain. 



Playinq in sandboxes 

The hybrid nature of an AIR application puts it somewhere in between 
both of these traditional security models. On the one hand, with AIR, you 
create a desktop application that runs on top of the normal OS security 
layer. Therefore, it can read and write from the local file system. However, 
because AIR uses Web technologies that, if unchecked, could be hijacked by 
a malicious third party and used in harmful ways when accessing the local 
system, Adobe AIR has a security model to guard against such an occurrence. 
Specifically, AIR runtime grants permissions to each source or data file in an 
AIR application based on its origin and places it into one of two kinds of con- 
tainers it calls sandboxes. 



The application sandbox contains all content that is installed with the app 
inside the home directory of an application. These are typically HTML, XML, 
JS, and SWF files. You can think of files inside the application sandbox as 
the equivalent of premium frequent flyer members that get full access to the 
special airport restaurants. Only these files have access to the AIR API and its 
runtime environment. 

Adobe AIR does allow you to link in other local and remote content that is 
not inside the root directory of the application, but places that content in a 
nonapplication sandbox. Content inside the nonapplication sandbox is essen- 
tially handled from a security standpoint just as a traditional Web app is, and 
is not granted access to the AIR APIs (see Figure 1-3). 

Check out Chapter 17 for more on application security and sandboxing. 



Additional restrictions utithin 
the application sandbox 

AIR places strict restrictions over script importing of remote content and the 
dynamic evaluation of JavaScript code — even inside the application sandbox. 
Many JavaScript programmers use the eval ( ) function as a way to gener- 
ate executable code on the fly. However, if you're loading data from a remote 
source, a hacker could potentially inject malicious code into your app without 
your knowledge. To prevent these security vulnerabilities, eval ( ) and other 
dynamic code methods are prohibited after the onload event occurs. 
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Figure 1-3: 
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As it is in Web applications, code being executed inside the application sand- 
box is free to load data using Ajax (the XMLHttpReqiiest object). However, 
any content received using XMLHttpRequest is treated purely as data and 
cannot be dynamically changed into executable JavaScript code (such as by 
using eval ( ) ). 



Table 1-1 lists the specific restrictions of what can be done inside an applica- 
tion sandbox. 



Table 1-1 Allowed and Nonallowed JavaScript Activities 


Language component Before onload 


After onload 


eval ( ) Permitted. 


Not permitted after an 
application loads, except 
when you use with a JSON 
type parameter to convert 
JSON strings into objects. 


document .write ( ) Permitted. 


Not permitted. 


Function constructor Permitted. 


Not permitted. 



(continued) 
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Table 1-1 (continued) 


^ y( n 4E&9 e component 


Before onload 


After onload 


setTimeout ( ) and 
setlnterval ( ) timing 
functions 


Permitted. 


Not permitted when using 
string parameters. 


JavaScript protocol URLs 

( j avascript : ) 


Not permitted. 


Not permitted. 


innerHTML, 
outerHTML properties 


Permitted. 


Attributes of inserted ele- 
ments cannot be trans- 
formed into executable 
code. 



XMLHttpRequest 



Synchronous calls 
outside the appli- 
cation sandbox 
prohibited. 



Asynchronous calls trig- 
gered in onload always 
finish after onload. 



Remote URLfor a Not permitted. Not permitted. 

<script> src 
attribute 



biqitaiiy Siqninq an Application 

Because users open their computer to an AIR app, their trust in the software 
publisher is crucial. They need to know that you won't do bad things to their 
private data or trash their hard drive. That's why digital signing is a required 
final step of the AIR application development process before you can deploy it. 

To provide a degree of confidence and trust, an AIR application must be 
signed by a code-signing certificate. There are two types of certificates: 

Self-signed certificates: "Do-it-yourself" certificates that you can gener- 
ate with the AIR SDK and then sign your app with. Self-signed certificates 
provide a minimal degree of trust, but because you have no outside 
confirmation that you are who you say you are, you are, in effect, tell- 
ing users, "Hey, you can trust me. Really. Really!" When users install an 
app with a self-signed certificate, they are warned that the publisher is 
UNVERIFIED (see Figure 1-4). 

Self-signed certificates are intended mainly for internal use when 
debugging and testing your app. 
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l^^pL Are you sure you want to install this 
| Y j application to your computer? 

X j"', Publisher UNKNOWN 



Figure 1-4: 

Self-signed 
certificates 
give no 
assurance 
to users. 



Publisher: 
Application: 
System Access: 




(x) Publisher Identity: UNKNOWN 

The publisher of this application cannot be determined. 

x System Access: UNRESTRICTED 

This application may access your file system and the internet, 
which may put your computer at risk. 




Commercial code-sign certificates: These certificates are purchased 
from a certification authority (CA), such as Verisign and Thawte, who 
authenticate your identity. A commercial certificate enables you to 
be considered a "trusted" publisher and gives users a much higher 
degree of confidence in working with your app. A commercial certificate 
enables users to verify the corporate or organizational affiliation of the 
application and ensures that users can say, "They are who we thought 
they were!" (see Figure 1-5). 

Commercial certificates, however, are not cheap. Fees are generally around 
$300 for one year and $549 for two years for a code-sign certificate. 



Application Install 



Are you sure you want to install this 
application to your computer? 

Publisher: The New York Times Company 
Application: ShifD 
System Access: U N RESTRICTED 



Figure 1-5: 

Commercial 
certificates 
add trust. 




Installing applications may present a security risk to you and your 
computer. Install only from sources that you trust. 

(5) Publisher Identity: VERIFIED 

x System Access: UNRESTRICTED 

This application may access your file system and the internet, 
which may put your computer at risk. 
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As you begin to work with Adobe AIR, you should begin by configuring your 
development environment. First, you should install the runtime and SDK. 
The SDK comes with two command-line tools that you can use to debug and 
deploy Adobe AIR apps: 

ADL is used for testing purposes only, enabling you to run an app 
without installing it. 

ADT is used for deploying your app. It packages the app into an 
installation package. 

Adobe also integrates the ability to package AIR apps inside Adobe Flash, 
Flex, and Dreamweaver (CS3 and later). However, if you use Dreamweaver, 
you should install the AIR extension to enable you to create AIR apps directly 
inside the Dreamweaver environment. 

The instructions to set up your environment are explained in the sections 
that follow. 



Installing the Adobe AlR runtime 

Adobe AIR runtime is the underlying engine that drives any AIR application. 
As a developer, you need the runtime installed on your machine in order to 
test and debug your apps. Users also need to download and install it on their 
computers in order to run an AIR application. 

Fortunately, installing the runtime is a quick, "no brainer" process. To install 
it, follow these four steps: 

1. Go to get . adobe . com/air in your browser. 
The Adobe AIR Web page opens. 

2. On the page, click the Download Now button. 

The installer file is downloaded onto your computer. 

3. Double-click the downloaded Adobe AIR Installer to launch the setup 
process. 

4. Follow the on-screen instructions to complete the setup. 
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Installing the Adobe AlR SDK 



the Adobe AIR runtime has a standard installer that you can use for 
on your computer, installing the SDK involves a few more manual 
steps. Follow these instructions to get it working on your computer: 

1. Go to www. adobe . com/products/air/tools/sdk in your browser. 

2. After reading the Adobe AIR SDK license, indicate that you agree with 
its terms by selecting the check box. 

3. Click the download link appropriate for your computer (Windows or Mac). 

The compressed SDK file — AdobeAiRSDK . zip (Windows) or 
AdobeAiRSDK . dmg (Mac) is downloaded to your machine. 

4. Create a folder on your machine for the SDK. 

I recommend something easy such as c : \airsdk for Windows or / 

Users/ [username] /airsdk for Mac. 

5. Uncompress the SDK file and copy the folders and files into the SDK 
folder you created in Step 4. 

The directory structure under your SDK folder (for example, c : \ 
airsdk) will look like this: 

\bin 

\ frameworks 
\lib 

\ runtime 
\ samples 
\src 

\ templates 

You now need to add the bin subdirectory to your system path before 
being able to execute the SDK utilities. Follow the appropriate steps 
below, depending on your operating system. 

Setting the environment path in Windows Vista 

1. Press the Windows key and the Pause/Break key at the same time. 

The System section of the Control Panel is displayed. 
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2. Click the Advanced System Settings link. 
A User Account Control dialog box is displayed. 

quired, enter the password for an Administrator account. 

4. Click the Continue button. 

5. Click the Advanced tab in the System Properties dialog box. 

6. Click the Environment Variables button. 

7. Edit the system variable named Path. 

8. At the far right end of the existing path value, type a semicolon and 
then the path for the bin subdirectory of the Adobe AIR SDK. 

9. Test the new path by opening a new Console window and typing adt 
at the command prompt. 

If you see a listing of the various usage options available when calling 
the utility, then you know you have successfully installed the SDK. If not, 
go back and check to ensure that you correctly added the SDK bin path. 

Setting the environment path in Windows XP 

1. Press the Windows key and the Pause/Break key at the same time. 
The System Properties dialog box is displayed. 

2. Click the Advanced tab in the System Properties dialog box. 

3. Click the Environment Variables button. 

4. Edit the system variable named Path. 

5. At the far right end of the existing path value, type a semicolon and 
then the path for the bin subdirectory of the Adobe AIR SDK. 

6. Test the new path by opening a new Console window and typing adt 
at the command prompt. 

If you see a listing of the various usage options available when calling 
the utility, you know you have successfully installed the SDK. If not, go 
back and check to ensure that you correctly added the SDK bin path. 

Settina the system path in Mac OSX 

Follow these steps to add the path of the AIR SDK to your system path: 

1. Open the Terminal application in your /Applications/Utilities 
folder. 

By default, you will be in your home directory. 
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2. Enter Is -la at the command prompt. 

Terminal will display a list of all files in your home directory, 
ck to see whether a file called . profile exists. 

If so, go on to Step 5. Otherwise, go to Step 4. 

4. If needed, create the .profile file by typing touch .profile at the com- 
mand prompt. 

5. Type open -a TextEdit .profile at the command prompt. 

6. Add your AIR SDK bin subdirectory to the export path=$path : 
line. 

Here's how mine looks: 

export PATH= $ PATH : /Users/rich/airsdk/bin 

If you already have an export path line, add the SDK bin folder to the 
far right, separating it with a semicolon. For example: 

export PATH= $ PATH : /usr/local/bin; /Users/rich/airsdk/ 
bin 

7. Save the file. 

8. Quit Terminal. 

9. Restart your computer. 

10. Open Terminal. 

11. Type the following in a Terminal window to load the new settings: 

. .profile 

12. Confirm the path by typing echo $PATH at the command prompt. 
You should see the SDK bin path in the output line. 

13. Test the SDK installation by typing adt at the command prompt. 

If you see a listing of the various usage options available when calling 
the utility, you know you have successfully installed the SDK. If not, go 
back and check to ensure that you correctly added the SDK bin path. 

Preppinq DreamWeaver and Flash for AlR 

If you use Dreamweaver or Flash CS3 or higher, you can package and preview 
applications directly inside the authoring environment, eliminating the need 
to use the command-line SDK tools. 
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To do so, begin by going to www. adobe . com/products/air/tools and 
downloading the appropriate software. For Dreamweaver, Adobe provides an 
nsion that you can install using the Adobe Extension Manager. For 
, you need to install a software update to enable this functionality. 



Chapter 2 

uftmng and Deploying Your First 
AIR Application with HTML and 

JavaScript 

In This Chapter 

Building an AIR app from scratch 
Creating an AIR interface using HTML and CSS 
Creating the application descriptor file 
Generating a self-signed certificate 
Producing an AIR installer file 



J^hhhhh, I get it. 

I can talk all day about Adobe AIR capabilities and architecture, but in order 
for you to really understand how to develop apps, nothing works better than 
walking through each step of the development process. In the experience of 
many developers, it is only when they build their first Hello World app that 
those precious words "Ahhhhh, I get it" are uttered. 

Developers, quite obviously, do not become instant experts after creating 
one simple application. But that first app does provide a context and a foun- 
dation for understanding the programming and procedural landscape of the 
platform on which they are working. 




In that light, this chapter is intended as the Ahhhhh, I get it chapter. I show 
the steps you need to take to build and deploy a basic Adobe AIR application 
using HTML and JavaScript. 
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ication I walk you through in this chapter is one I call Jot. Jot has 
one limited purpose — to allow a user to enter text in a box and save the 
text to a file on the desktop. I spice things up a bit by adding my own custom 
"chrome" user interface. You can follow along with my code to build a dupli- 
cate version or download the entire source code at www. dummies . com. 

To help you build Jot, I walk you through a series of eight steps, as follows: 

1. Prepare the application folder. 

2. Create the HTML-based UI. 

3. Define CSS styles. 

4. Add the JavaScript code. 

5. Create the application descriptor file. 

6. Create a self-signed certificate. 

7. Compile the application. 

8. Take a test drive. 

The remaining sections of this chapter present the details of each of these steps. 

Preparing the Application Folder 

Your first step in creating Jot is simply to prepare a folder on your hard drive 
that will serve as the root for the application files. To prepare that folder, 
follow these three steps: 

1. On your hard drive, create a new folder named jot. 

This folder will serve as the root folder containing all the application 
files. 

2. Inside the new jot folder, create two subdirectories: assets and 
icons. 

The assets folder will store your . j s and .ess styles. The icons 
folder will contain the application icons. 

3. Copy the AiRAliases . j s file into the assets folder. 

The AiRAliases . j s file is located inside the SDK frameworks folder. 

With your application folder ready to go, it's time to begin creating the 
application itself. 
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ction, you create the Jot application using an ordinary HTML page 
as the user interface (UI). You'll be putting styles and script code elsewhere, 
so the actual application file contains basic markup only. Here are the steps 
to create the Jot application: 

1. Use the following code to create a basic XHTML document shell. 

Yes, an HTML-based AIR application begins its life looking an awful lot 
like a normal Web page. It's even named index . html by default. That's 
because it is a normal HTML file. Here's the code: 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 

Transitional //EN" "http: //www.w3 .org/TR/ 
xhtml 1 /DTD/xhtml 1- transitional . dtd" > 

<html xmlns= "http : / /www . w3 . org/ 199 9 /xhtml " > 

<head> 

<meta http-equiv=" Content-Type" content= " text/html ; 

charset=utf -8 " /> 
<title>Jot</title> 
</head> 
<body> 

</body> 
</html> 

2. Add a link reference to a stylesheet named jot . ess inside the head 
element. 

You'll create the j ot . ess file in the next section, but for now, add the 
link: 

<link type= " text/ess " href="assets/jot.css" 
rel= " stylesheet " /> 

3. Add script tag references to AiRAliases . j s and j ot . j s in the 
head element. 

As with the style sheet above, you'll create the j ot . j s later on. For 
now, just add the following reference: 

<script type=" text/ javascript" language= "JavaScript" 
src= "assets /AiRAliases . j s " ></script> 

<script type=" text/ javascript" language= "JavaScript" 
src= "assets/ j ot . j s " ></ script > 

You use the AiRAliases . j s file to access the AIR API. 

4. Insert a div element with an id=canvas on the line below the 
opening body tag. 

The canvas div will serve as the container for the UI: 

<div id=" canvas "> 
</div> 
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5. Add an hi tag on the first line inside of the div element. 

Because this app has a custom UI, it will not have a normal title bar for 
indow. So, the hi tag will serve as the app title: 



hl>Jot</hl> 

6. Add a textarea element on the line below the hi element. 

The textarea box will be used for text entry: 

<textarea id=" jotText">Enter your text here</ 
textarea> 

7. Insert two input buttons on the lines below the textarea. 

These will be used for saving the text file and for closing the application. 
Here's the code: 



< input 


id= 


"btnSave " 


type= " submit " 


value= " 


Save 


Jot" /> 


< input 


id= 


"btnClose' 


' type= " submit 1 


' value= 


"Clo 


se" /> 



The complete source code to index . html is as follows: 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 

Transitional //EN" "http: //www.w3 . org /TR/ xhtml 1 / 
DTD/xhtmll-transitional .dtd"> 

<html xmlns= "http : / /www. w3 . org/ 1999 /xhtml " > 

<head> 

<meta http-equiv=" Content-Type" content= " text /html ,- 

charset=utf -8 " /> 
<title>Jot</title> 

<link type= " text/ess " href ="assets/ jot . ess" 

rel= " stylesheet " /> 
<script type=" text /javascript" language=" JavaScript" 

src= " asset s/AIRAliases . j s " ></script> 
<script type=" text /javascript" language=" JavaScript" 

src= "assets/ jot . j s " ></ script > 

</head> 
<body> 

<div id= " canvas " > 
<hl>Jot</hl> 

<textarea id=" jotText">Enter your text here</textarea> 
< input id="btnSave" type= " submit " value="Save Jot" /> 
<input id="btnClose" type= " submit " value="Close" /> 

</div> 

</body> 

</html> 



You're now ready to give this basic XHTML file some style. 
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Jjqf\^^this is an HTML-based application, I have you add styles and format- 
ting using CSS. You already added the link to j ot . ess in the HTML file, so 
now you can create this style sheet. To do so, follow these steps: 

1. Create a blank text file and save it as j ot . ess in your assets folder. 

2. Insert a #canvas rule to define styles for the canvas div. 
The code contains both standard CSS and WebKit extensions: 

#canvas { 



font-family: ' Lucida Grande', Verdana, Geneva, Sans- 

Serif ; 
font-size: lOpx; 
text-align: center; 
color: #ffffff; 
padding : 5px; 

background : url ( 'background. png ' ) repeat-x 0 0 ; 
-webkit-background-size : 100%; 
-webkit-border-radius : 5px; 



The -webkit-background-size : 100% rule prevents the back- 
ground image from tiling and stretches the background image to be the 
size of the div. 

You can use your own background image or else use the one I did by 
downloading it from the book's Web site at www. dummies . com/go/ 
adobeair. 

Notice my use of the -webkit-border-radius property. This WebKit 
extension is used for rounding the corners of the div. That's certainly 
much easier than adding rounded corners using graphics! 

If you're a Web developer, designing for a single browser rather than for 
all browsers can be a difficult adjustment to make. However, because 
you're developing your AIR application only for WebKit, be sure to take 
advantage of WebKit-specific extensions. 

3. Add styles for the hi and textarea elements. 

The textarea rule defines the dimensions of the element. It also 
assigns the transparent value to the background-color property: 

hi { font-size : 1 . 3em; } 

textarea { 
width:210px; 
height: 2 00px; 
padding : 5px ; 
margin-bottom: 5px; 
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background-color: transparent; 
color: #ffffff; 
border : 0 ; 
webkit-border-radius : 5px; 



} 



Note that I define rounded corners for the textarea, which is displayed 
when the element receives focus. 

4. Add styles for the submit buttons. 

To give the submit buttons a rounded look (like everything else in Jot), I 
turn once again to -webkit-border-radius. However, I also want to give 
the buttons more of a 3D feel by styling the border-color as follows: 

input [type=submit] { 
width: 66px; 
color: #ffffff; 
background-color: #222222; 
border: lpx outset #444444; 

border-color: #444444 #000000 #000000 #444444; 
-webkit-border-radius: 8px; 

} 



input [type=submit] : hover { 



COlor:#ffffff ; 






background-color: # 

} 


333333; 





As you can see, I added a : hover pseudo-class definition so that the 
color changes as the mouse hovers on it. 



The full listing for the j ot . ess file is follows: 



#canvas { 

font-family: 'Lucida Grande', Verdana, Geneva, Sans- 
Serif ; 
font-size: lOpx; 
color: #ffffff; 
text-align : center ; 
padding : 5px; 

background: url ( 'background. png ' ) repeat-x 0 0 ; 
-webkit-background-size : 100%; 
-webkit-border-radius: 5px; 



hi { font-size : 1 . 3 em; } 



textarea { 
width: 210px; 
height: 2 00px; 
padding : 5px; 
color: #ffffff; 
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background-color : transparent ; 
margin-bottom: 5px; 
er : 0 ; 

kit-border-radius: 5px; 



input [type=submit] { 
width: 66px; 
color: #ffffff; 
background-color : #222222 ; 
border: lpx outset #444444; 

border-color: #444444 #000000 #000000 #444444; 
-webkit-border-radius : 8px; 



input [type=submit] : hover { 
color: ttffffff; 
background-color: #333333; 

} 



The user interface of the application is now ready to go. Now you can add the 
scripting. Read on! 



nq the JavaScript Code 



Jot is powered by the JavaScript code that is placed inside of the j ot . j s file 
that you linked in earlier into the index . html file. You need to code Jot to 
perform four simple functions: 

Save text to a file when the Save button is pressed, 
f* Allow a user to move a window when the mouse button is held down. 
Automatically resize the application to the size of the HTML content. 
Close the app when the Close button is clicked. 

You begin by adding some basic JavaScript utility routines, and then you can 
add the custom code for Jot. 



Note I've placed in bold type all AIR API-specific calls that I make in the code 
in some of the following steps. 

1. Add basic JavaScript utility functions for accessing the DOM and binding 
objects to functions. 

These core utility functions are both handy and important to have for 
even the simplest of projects. Here's the code: 
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/ / Shortcut function to access DOM id 
function $ ( id) { 

return document . getElementByld ( id) ; 




// Bind objects to functions 

Function. prototype. bind = function (o, args){ 
var f = this; 
return function! ){ 

f. apply (o, args | | arguments); 

} 

} 

2. Define a Jot object and an initialize ( ) method. 

You structure this code by putting all the application logic inside a Jot 
object. At the same time, you define an initialize ( ) method that will 
be called when the application loads. Here's the code: 

var Jot = { 

initialize : function ( ) { 
} 

} 

You add the Jot . initialize ( ) as a listener to the window load event 
later on, in Step 10. 

3. Inside Jot, define the basic shell structure for the save (), close () , 

and ref reshsize ( ) methods. 

You can go ahead and leave these empty for the moment, but it's helpful 
to define them first before you fill in the initialization routine. The code 
(with empty functions) is as follows: 

var Jot = { 

initialize : function ( ) { 
}, 

save : function ( ) { 
}, 

close : function ( ) { 
}, 

ref reshsize : function ( ) { 
} 



} 
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4. Inside initialize ( ) , attach the onclick handlers of the buttons to 
the newly defined save ( ) and close ( ) methods. 

s where the utility functions come in handy: 



$(' btnSave '). onclick = Jot . save . bind (Jot ) ; 
$(' btnClose '). onclick = Jot . close . bind (Jot ) 



You want to place the following code on the first lines inside 

initialize ( ) . 

In this code, the Jot . save ( ) and Jot . close ( ) methods are assigned 
as the handlers to the buttons' onclick events. The bind ( ) methods 
bind the associated functions to the Jot object. 

5. Register an event listener with the window closing event. 

This is the first interaction you make with the AIR API. You want your 
app to be able to "listen" to the closing event that is dispatched by the 
window when it is getting ready to close. This event could be triggered 
when the Mac OS X Quit command or a Windows Close command is 
performed. In this case, I want to call the Jot . close ( ) method: 

window. nativeWindow. addEventListener (air . Event . 
CLOSING, Jot. close. bind(Jot) ) ; 

The air object is defined in AiRAliases . j s that you included previ- 
ously in the index . html file. 

6. Assign a handler to the onmousedown event of the document body. 

Because I'm having you use a custom chrome window rather than a 
normal system window, you need to add the ability for the user to move 
the window around. You do that by writing your own custom handler for 

the onmousedown event: 

document . body . onmousedown = function(e){ 

if (e . target . tagName != 'input') nativeWindow. 
startMove ( ) ; 

}; 

This function calls the startMove ( ) method of the AIR runtime object 
nativeWindow, which controls the application window. (Note: AIR's 
nativeWindow is technically not the same object as the JavaScript 
window object.) 

The initialize ( ) method is now complete. 

7. Define the save ( ) method. 

Enter the code as follows (you don't have to use bold, as I do here; the 
bolded sections just highlight the AIR-specific functionality of the function): 
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save : function ( ) { 
var file = air. File. desktopDirectory. resolvePath( 
1 my j ot . txt 1 ) ; 
ar jot = $( 'jotText' ) .value; 
var stream = new air.FileStream( ) ; 
stream. open( file, air. FileMode. WRITE ); 
stream. writeMultiByte ( jot, air. File. systemCharset 
); 

stream. close ( ) ; 

} 

The resolvePath ( ) method creates a reference (the file variable) 
to a file named myj ot . txt in the desktop folder of the user. Next, the 
value of the j otText textarea element is assigned to the j ot vari- 
able. You then use the AIR file I/O routines to create a file stream, open 
it up for writing, write the jot variable to the stream, and then close it. 

8. Define the closet) method. 

Before the application quits, the close ( ) method checks to see 
whether the user wants to save the text. If yes, then the Jot . save ( ) 
method is called. Here's the code: 

close: function (evt) { 

var doSave = confirm ('Do you wish to save your 

jot? Click OK to save. Click Cancel to close 
without saving. ' ) ,- 
if(doSave) { 

Jot . closeAf terSave = true; 
Jot . save . call (Jot ) ; 

} 



air. NativeApplication.nativeApplication. exit ( ) ; 

} 

NativeApplication is an object created automatically by AIR that 
contains various application-level properties and methods. However, 
to actually call any of its members, you access it through its air . 
NativeApplication. nativeApplication property. This property 
represents the "singleton" instance of the object. The exit ( ) method, as 
you would certainly expect, gives the old curtain call to the application. 

9. Define the refreshsize ( ) method. 

Although you will be defining a default height and width for the Jot 
window, you want to be sure to automatically size the height of the 
window to match the document body. You can accomplish this feat by 
adding the following code: 
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ref reshSize : function ( ) { 

nativeWindow. height = document .body. of fsetHeight ; 



1 Tjfrai the simplicity of this application, I actually could certainly get by 
with hard coding the height value for the nativeWindow. But this gives 
you an example of the flexibility you can have in dynamically changing 
the size of the window during the running of the app. 

There's just one more thing you need to do in j ot . ess: trigger Jot . 
initialize ( ) when the document loads, which the next step covers. 

10. Outside the Jot definition, add an event listener for the window load 
event. 

Returning to normal JavaScript stuff, you need to be sure that Jot . 
initalize ( ) is triggered when the app finishes loading: 

window. addEventListener (' load ' , Jot . initialize , 



If you have followed each of the preceding steps, your full source code in 
j ot . j s should look like the following: 

// Utility functions (based on Prototype . j s ) 
function $ ( id) { 

return document . getElementByld ( id) ; 

} 

// Bind objects to functions 

Function. prototype. bind = function(o, args){ 
var f = this; 
return function () { 

f. apply (o, args | | arguments); 

} 

} 

var Jot = { 

initialize : function ( ) { 

$(' btnSave '). onclick = Jot . save .bind (Jot) ; 
$(' btnClose '). onclick = Jot . close .bind (Jot ) ; 

window . nativeWindow. addEventListener ( air . Event . 
CLOSING, Jot. close. bind(Jot) ) ; 

document .body . onmousedown = function (e) { 

if (e . target . tagName != 'input') nativeWindow. 
startMove ( ) ; 

Jot . ref reshSize ( ) ; 




false) ; 



}; 
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e : function ( ) { 

r file = air. File. desktopDirectory . 
resolvePath ( 'myjot.txt' ) ; 
var jot = $( 'jotText' ). value; 
var stream = new air . FileStream ( ) ; 
stream. open ( file, air . FileMode .WRITE ) ; 
stream. writeMultiByte ( jot, air . File . systemCharset 
stream. close ( ) ; 



close : function (evt) { 



var doSave = confirm ('Do you wish to save your jot? 

Click OK to save. Click Cancel to close without 
saving . ' ) ; 
if(doSave) { 

Jot . save . call (Jot) ; 

} 

air .NativeApplication.nativeApplication . exit ( ) ; 



}, 

ref reshSize : function ( ) { 

nativeWindow . height = document . body . of fsetHeight ; 

} 



window. addEventListener (' load ' , Jot . initialize, false); 



Creating the Application Descriptor File 

Accompanying your main source files is a separate XML file known as the 
application descriptor file. This file is required to define metadata for your 
application and specify your initial window properties. You can follow these 
steps to define the application descriptor file. 

1. In your root application directory, create a blank text file and name it 

application . xml. 

Technically, you can name the . xml file anything you want, such as 
j ot . xml. However, because the name of this file is not related to the 
actual filename of your AIR application, you may find it helpful to keep 
the file generic and use application . xml. 
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2. Add the XML header and root application element at the start of 

the application . xml file. 

application element serves as the root element for the file and 
immediately under the XML header, like so: 

<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 
<application xmlns= "http : / /ns . adobe . com/air/ 

application/1 . 0 " minimumPatchLevel= " 533 1 " > 
</application> 

The xmlns namespace specifies that your application targets the 1.0 version 
of AIR. The minimumPatchLevel attribute helps the AIR runtime determine 
whether a user needs to download and install a required version or patch. 

3. Add basic metadata descriptors inside the application element. 

There are several elements that you will want to define for almost any 
application. These include: 

<id>com. dummies . j ot</id> 
<version>l . 0</version> 
<f ilename> j ot</ f ilename> 
<name> Jot< /name> 

<description>Jot smart and silly notes</description> 
<copyright>Copyright © 2008, Rich Wagner</copyright> 

The required id element specifies a unique identifier for every AIR 
application. As you can see, it uses reverse domain format, starting with 
the domain suffix, the domain name, and then the application name. By 
using every developer's unique domain name, reverse domain format- 
ting ensures that the application can have a unique identifier across the 
namespace. 

The version element is required and indicates the version of your 
application. The actual notation you use is up to you. AIR doesn't try to 
determine which version is earlier or later than the next from this value. 

The filename element is also required. It defines the filename (without 
the extension) of your application. The . air installer file and actual appli- 
cation executable (Windows . exe or Mac OS X . app) will use this value. 

The name, description, and copyright elements are optional. If 
defined, they are displayed in the installer dialog box. 

4. Add descriptive details for the initial window inside the application 
element. 

The initialWindow element is used by the AIR runtime to create the 
opening window based on the settings you specify. Here are the details 
for Jot: 
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<initialWindow> 

<content> index . html< /content> 
<height>3 5 0< /height > 
<width>2 5 0< /width> 
<systemChrome>none< / systemChrome> 
<visible>true</visible> 
< / initialWindow> 



The content element indicates the main HTML or SWF (Flash) file of 
the application. The height and weight specify the dimensions of the 
window. 

The systemChrome element specifies whether to add "chrome" to the 
window. Possible values are standard and none. Because this is a 
custom chrome application, I am specifying none. 

The visible element determines whether the window should be visible 
as soon as it is created. The default is false, meaning that your code 
would need to show the window. 

5. Specify icon files. 

You can specify icon files to represent your application on the user's 
computer. Because different parts of a UI use different sizes of an icon, 
you can specify 16 x 16, 32 x 32, 48 x 48, and 128 x 128 files. 

I created four png icons and copied them to the icons directory inside 
of the application root. Here's the code: 

<icon> 

<imagel2 8xl2 8>icons/128 . png</imagel2 8xl28> 
<image48x48> icons /48 .png</image48x48> 
<image32x32>icons/32 .png</image32x32> 
<imagel6xl6>icons/16 .png</imagel6xl6> 
< / icon> 

If you don't specify any icon files, the AIR compiler will use a default 
AIR icon. 



The application . xml file is all set. Here is the full file: 

<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 
<application xmlns= "http : / /ns . adobe . com/air/ 

application/1 . 0 " minimumPatchLevel= " 533 1 " > 
<id> com. dummies . j ot< / id> 
<version>l . 0</version> 
<f ilename> j ot< / f ilename> 
< name > Jo t </ name > 

<description>Jot smart and silly notes</description> 
<copyright>Copyright © 2008, Rich Wagner</copyright> 
<initialWindow> 

<content>index . html</content> 

<height>3 50</height> 

<width>250</width> 
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<systemChrome>none</systemChrome> 
<visible>true< /visible> 
itialWindow> 
n> 

imagel28xl28>icons/12 8 .png</imagel2 8xl2 8> 
< image4 8x4 8 >icons / 4 8 . png< / image4 8x4 8> 
<image32x32>icons/32 .png</image32x32> 
<imagel6xl 6 > icons / 1 6 . png< / image 1 6x16 > 
</icon> 
</application> 



Testing \lour Application Using AOT 

If you've followed along through the previous sections of this chapter, you've 
now assembled all the parts of the core application. It is time to test your 
application on your computer to make sure it works properly. To do so, 
you'll use ADT, a command-line utility that is included as part of the AIR SDK. 




Before continuing, be sure that you have installed the AIR SDK and that the 
AIR SDK bin directory is in your system path. If either of these need to be 
done, see Chapter 1 for step-by-step instructions. 



1. To test your application, open a Console (Windows) or Terminal 
(Mac) window. 

2. Using the CD command, change to your application's root directory. 

This is the directory in which all your application's source code is 
located. 

3. Enter adl application.xml at the command prompt and press Enter. 

Figure 2-1 shows the Mac OS X command prompt. 



Terminal — bash — 80x24 

_l 



trufflehunter:- rich$ cd '/Users/rich/Developaent/airdev/HTML/Jot/' 
trufflehunter: Jot rich! adt application. x»l 



Figure 2-1: 

Testing the 
AIR app 
using ADT. 
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Jot will launch in debug mode, as shown in Figure 2-2. 

Perform the following tasks to confirm the functionality that you pro- 
med into the application: 

Type something into the text box and click Save. Open the my j ot . 
txt file on your desktop in Notepad or another text editor and 
check out the contents. If your app is working, you see exactly the 
same text. 

• Click the mouse somewhere on the app (except for the buttons) 
and drag the window. If your app is functioning correctly, the 
window moves around the way any other native OS window does. 

• Click the Close button and test the save options. If you modified 
text in the text box, the app should ask you whether you want to 
save the contents. 

If you modified text and the app just closes, something went awry. In 
that case, go back through this example and double-check your code. 



Jot 

Enter your text here 




Figure 2-2: 

Jot comes 
to life. 



Creating a Setf-Siqned Certificate 

As I note in Chapter 1, every AIR application needs to be digitally signed. You 
can sign the app either through a Certification Authority or through the do-it- 
yourself econo-mode method of a self-signed certificate. Chapter 1 explains 
the differences between these two methods and the advantages and disad- 
vantages of each. But for the Jot application you develop in this chapter, you 
want to keep things simple with a test self-signed certificate. Here's how to 
create one using the ADT utility. 

1. Open a Console (Windows) or Terminal (Mac) window. 

2. Enter CD at the command prompt to change to your application root 
directory. 
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3. Enter the following at the command prompt: adt -certificate -cn certl 
1024-RSA testcert.pl2 password to generate the certificate. 



basic syntax for creating a self-signed certificate is as follows: 




-certificate -cn commonName keyType 
certif icateFile password 



When you use this syntax in the command line, you instruct ADT to 
create a certificate with a common name of certl, a 1024-rsa key 
type, a filename of testcert .pl2, and a password of password. 

The testcert .pl2 file is created in your application root directory. 

Given its weak password, you would not want to use this certificate on an 
application you intended to distribute. The certificate would work fine for 
your own internal testing, though. 

Also, don't worry: You don't need to create a new certificate for each applica- 
tion. You can use one certificate multiple times. 



You're now ready to perform the final step in building and deploying an 
application: generating a distributable AIR file. 



Generating an AlK Installer File 
to Deploy \/our Application 

If you've been following along through this chapter, you are nearly finished 
with your first AIR application. By now, you have all the pieces of the Jot 
application assembled. Now, you have one final step: produce the .air file 
that you will use to deploy your app. 

To generate the . air file, follow these steps: 

1. Open a Console (Windows) or Terminal (Mac) window. 

2. Enter CD at the command prompt to change to your application root 
directory. 

3. Type in the following command at the prompt: 

adt -package -storetype pkcsl2 -keystore testcert. pl2 
jot. air application. xml index.html assets/jot. 
ess assets/ jot . j s assets/AIRAliases . j s assets/ 
background. png icons/128 .png icons/48. png 
icons/32. png icons/16 .png. 
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This long-winded command-line instruction tells ADT to produce jot. 
air using the application . xml descriptor file and include all the files 
e application. The self-signed certificate testcert .pl2 (created in 
revious section) is used as the signing option. 

Note that you need to have the proper icons and background image file 
in the assets subfolder in order to make that work. If you don't have 
your own, go to www. dummies . com/go/adobeairf d and download 
the ones I use. 

You will be prompted for the certificate password. 

4. Enter password at the command prompt. 

ADT will do its magic and generate the j ot . air file in your application 
directory. 

Now, when you double-click the j ot . air installer file, the Application Install 
dialog box is displayed, as shown in Figure 2-3. 



Figure 2-3: 

Installing 
Jot with a 
self-signed 
certificate. 



Are you sure you want to install this 
application to your computer? 



Publisher 
Application 
System Access: 



UNRESTRICTED 




Installing applications may present a security risk to you and your 
computer. Install only from sources that you trust. 

(x) Publisher Identity. UNKNOWN 

The publisher of this application cannot be determined. 

ix. System Access: UNRESTRICTED 

This application may access your file system and the internet, 
which may put your computer at risk. 
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In This Chapter 

Creating an AIR app with Flex 
Using Flash to create an AIR app 



r 

•"^lash and its newer sibling Flex Builder enable developers to create rich 
m media and applications for the Web. However, because Adobe AIR is 
built on top of underlying Flash technology, they also serve as ideal envi- 
ronments for creating AIR apps for the desktop. In this chapter, I walk you 
through the steps of creating a basic AIR app in Flex and Flash. 

I don't explain how to use Flex or Flash in this chapter or elsewhere in the 
book; instead, this chapter covers how to access the AIR functionality that 
you can utilize within these Web development environments. 

Dei/eloping art AlK Application 
With Flex Builder 3- 0 

When you create a new Flex project in Flex Builder, you can choose whether 
the application you're building is for the Web or for the desktop. Follow these 
soup-to-nuts instructions to create a sample desktop-based AIR app in Flex 
Builder that I'm calling JotFlex. 
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Creating the project 



t step in creating an AIR-based Flex app is to use the Create Project 
o generate the basic files for the project. Follow these steps: 

1. Choose FileONewOFlex Project. 

The New Flex Project dialog box appears, as shown in Figure 3-1. 



Create a Flex project. 

Ctioose a name and location for your project, and configure the server technology your project will be using. 



0 Use default location 

Folder: /Users/ rich /DevelopmenUairdev/Flex 

Application type 

2] We -j application (runs in Hash Player) 
@ g Desktop application (runs in Adobe AIR) 

Server technology 

Application server type: 1 None *H 

v Um remote object access service 
(_) UveCycle Data Service* 
Q ColdFusion Tash Remoting 



Figure 3-1: 

The New 
Flex Project 
dialog box. 



< aac» iSe.t > C Cancel ) 



2. In the Project name box, enter JotFlex as the name of the AIR project. 

3. In the Project location box, specify the location of your project. 

Flex defaults to its own project folder in your Documents folder. Use the 
default or specify another of your choice. 

4. Select the Desktop Application (Runs in Adobe AIR) option in the 
Application type box. 

5. Leave the Server technology box alone. 

6. Click the Next button to continue. 

The Configure Output page is displayed. 

7. Specify the desired output location for the compiled application in the 
Output folder box. 

Go ahead and leave this at the default folder, bin-debug. 

8. Click the Next button to continue. 

The Create a Flex project is displayed. 
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You can ignore the top part of the dialog box for this basic example. You 
use that section to add source code or Flash library files into your app. 



sired, modify the values in the Main source folder and Main appli- 
bn file boxes. 




You'll probably want to just leave these as is, because these are the typi- 
cal settings used in Flex apps. 

10. Modify the Application ID to give it a unique, package-like name. To 
do so, add a com.yourdomain. prefix to the application name. 

The application ID I use for this example is com. dummies . JotFlex. 

Be sure to specify a "reverse domain name" — in other words, it's like a 
Web site address in reverse. The com comes first, followed by a unique 
domain name, followed by your app name. Flex Builder will not compile 
your application successfully if you leave the value as is. 

Figure 3-2 shows the dialog box. 

11. Click the Finish button. 

The new project is created and added to the Flex Navigator, and the 
main MXML source file is displayed in the editor window, as shown in 
Figure 3-3. 



Figure 3-2: 

Specifying 
the name 
of the 
application. 



New Flex Project 



Create a Flex project. 

Set the build paths for th 



:e path e Library path 



Additional source folders outside of the main source folder: 



e folder: [sr 



Main application hie: JotFlex.n 
Application ID com. dun 



( <Back "I 



( Add Folder... ) 

D 



C 



J G 



D 



( Browse... ~ ) 
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Notice the root element used in the MXML file. Whereas mx: Application is 
the root element for Flex Web applications, mx:WindowedApplication is the 
root for an AIR application. 

Adding MXML and ActionScript 
source code 

After you're created your basic files, you're ready to work with MXML and 
ActionScript to create your app. Follow these steps to continue. 

1. Specify five attributes to the mx : windowedApplication element. 

In addition to the default settings, specify the title, width, height, 
verticalScrollPolicy, and horizontalScrollPolicy values, as 
follows: 

<mx: WindowedApplication xmlns :mx="http: //www. adobe . com/ 2 0 0 6 /mxml " 
layout=" absolute" title="JotFlex" width="321" height="297" 
verticalScrollPolicy="of f " horizontalScrollPolicy="of f "> 

By setting the verticalScrollPolicy and horizontalScroll 
Policy properties to "off," you are disabling scroll bars and keeping 
them from appearing. 
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2. Inside the mx : windowedApplication element, add an mx : TextArea 
element. 



oks 

<mx 



element will be used for text entry: 

:TextArea id="taEditor" x="13.5" y= ,, 10 M width="292 11 height=" 197 "/> 

3. Add two mx : Button elements below the mx : TextArea: 



<mx:Button id="btnClose" x="100.5" y="215" label="Close" 
clicks "closeApp ( ) "/> 

<mx:Button id="btnSave" x="161.5" y="215" label="Save" click="saveApp ( ) " /> 

Note the click event handlers added in this step. You'll see how to 
define the closeApp ( ) and saveApp ( ) functions in Steps 5 and 6. 

4. Add an mx: Script element just after the mx: windowedApplication 
start tag: 

<mx: Script> 
</mx: Script> 

5. Type the saveApp ( ) function inside the script: 

public function saveApp (): void { 

var file: File = File . desktopDirectory . resolvePath ( 
"myj ot . txt " ) ; 

var jot: String = taEditor . text ; 

var stream:FileStream = new FileStream () ; 

stream. open ( file, FileMode .WRITE ) ; 

stream. writeMultiByte ( jot, File . systemCharset ) ; 

stream. close ( ) ; 

} 

If you've used Flex before for Web development, the File and 
FileStream objects may look foreign to you. That's because you can't 
use those objects with Web-based apps. (See Chapter 10 for more on 
File and FileStream.) 

In this function, the file variable is assigned as a reference to the 
myjot . txt in the desktop folder of the user. The text contents of 
taEditor are assigned to the j ot variable. You then use the AIR file 
I/O routines to create a file stream, open it for writing, write the jot 
variable to the stream, and then close it. 

6. Type the closeApp ( ) function inside the script: 

public function closeApp (): void { 

NativeApplication . nativeApplication . exit ( ) ; 

} 
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NativeApplication contains various application-level properties and 
methods. However, to actually call any of its members, you access it 
ugh its NativeApplication. nativeApplication property. Its 
it ( ) method closes the application. 



Here's the full source for the JotFlex.mxml file: 



<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 

<mx : WindowedApplication xmlns :mx= "http : / /www. 

adobe . com/ 2 006 /mxml " layout= " absolute " 

title=" JotFlex" 
width="321" height="297" verticalScrollPolicy= " of f " 

horizontalScrollPolicy= " of f " > 



<mx: Script> 
<! [ CDATA [ 

public function saveApp ( ) : void { 

var file: File = File . desktopDirectory . resolvePath ( 

"myj ot . txt " ) ; 
var jot: String = taEdi tor . text ; 
var stream : FileStream = new FileStream () ; 
stream. open ( file, FileMode .WRITE ); 
stream. writeMultiByte ( jot, File . systemCharset ); 
stream. close ( ) ; 



public function closeApp ( ) : void { 

NativeApplication. nativeApplication. exit ( ) ; 

} 

] ]> 

</mx : Script> 



<mx:TextArea id="taEditor" x="13.5" y="10" width="292" 

height="197" /> 
<mx:Button id= "btnClose " x="100.5" y="215" label= " Close " 

click= " closeApp ( ) " /> 
<mx:Button id="btnSave" x="161.5" y="215" label="Save" 

click= " saveApp ( ) "/> 

</mx : WindowedApplication> 



You're now ready to work with the application descriptor file. 
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Configuring the application descriptor file 



need to configure the application descriptor file, which is an XML 
rovides basic application-level details about the application. Follow 
these steps next. 

1. In the Flex Navigator, double-click the application descriptor file for 
the AIR project. 

You'll find it located in the src file, with the filename application- 
Name -app .xml. For the example project being developed in this sec- 
tion, it's called JotFlex-app . xml. 

The file is displayed in the editor, as shown in Figure 3-4. 

2. Locate the systemChrome element and uncomment it. 

This property specifies the type of system chrome to use. (See Chapter 
7 for more on system chrome.) The standard value gives the native OS 
chrome, whereas none removes it. 

By default, the systemChrome element is commented out in the XML 
document. To get a sense of what a Flex chromed AIR app looks like, 
specify none here. 

3. Add none as the systemChrome value. 
The element will look like this: 

<systemChrome>none</systemChrome> 
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4. Locate the transparent element and uncomment it. 

The transparent element is commented by default. 

true as the transparent value. 

The element is as follows: 

<transparent>true</ transparent> 

6. Choose FileOSave All from the menu to save all changes. 

With all the code added to the app, you are ready to test the example 
application that you've developed in this section. 



Testing the app 

You now have all the pieces ready for your first AIR app coded and are ready 
to roll. You can test the app by following these steps: 

1. Choose RunORun JotFlex from the top Flex menu. 

The JotFlex application is displayed, as shown in Figure 3-5. 

2. Test the functionality of the Save and Close buttons before finishing 
your testing. 

When you're satisfied with the state of the application, you're ready to 
create an installable .air file. 
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Preparing the app for deployment 



I app is coded and tested. The final step is to prepare the application 
'yment. 



1. Choose ProjectOExport Release Build from the top Flex menu. 

You can also click the Export Release Build icon on the toolbar. 

The Export Release Build dialog box is displayed, as shown in Figure 3-6. 



Export Release Build 



Export Release Build 

Build and export an optimized release-quality SWF or Adobe AIR application installer. 



Figure 3-6: 

Exporting an 
AIR project. 



Project: ( KKFlex 



Application lotFlex.mxml 



I 1 Enable view source 



P Choose Source Files... ) 



Export to file: JotFlex.air 
(in /JotFlex) 



_3 



( Browse... ) 



( Next > ) ( Finish ^ ( Cancel ~j 



You can keep all the default values for this application. 

2. Click the Next button to continue. 

The Digital Signature page is displayed (see Figure 3-7). 

You now need to create a self-signed digital certificate for this sample 
application. 
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Figure 3-7: 

Specifying 
a digital 
signature 
during the 
export 
process. 



Export Release Build 



Digital Signature 
Qllo certificate selected. 



© Export and sign an AIR file with a digital certificate 
Certificate: 



■»j ( Browse... "> ( Create... ^ 



^ Remember password for this session 
Timestamp 

Q Export an intermediate AIRI file that will be signed later 



Carre 



3. Click the Create button. 

The Create Self-Signed Digital Certificate dialog box is displayed, as 
shown in Figure 3-8. 



Figure 3-8: 

Creating a 
self-signed 
certificate in 
Flash. 



Create Self-Signed Digital Certificate 



Publisher name: 
Organization unit: 
Organization name: 

Country: fus ~*\ 
Password: 
Confirm password: 



Type: 1 1024-RSA 



f BrowseTT^ 



Help 



( Cancel j 



4. Enter your name in the Publisher Name box. 

5. Enter a password in the Password and Confirm Password boxes. 
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6. Click the Browse button. 

■ The Save dialog box appears. 



The Create Self-Signed Certificate dialog box appears again. 

8. Click the OK button. 

The Digital Certificate page is displayed again. 

9. Click the Finish button. 

The JetFlex . air file is created and now ready for deployment. 
If you would like to deploy the app, jump on over to Chapter 14. 



Flash has become the clear standard for creating rich media within the 
browser, so "Flash" and "Web page" are nearly synonymous terms these 
days. But now, Flash developers are no longer limited to browser-based solu- 
tions. Instead, you can take advantage of AIR to create apps for the desktop. 
This section offers an example of creating a basic AIR application using Flash. 



Begin creating your application by designing its user interface. I keep the 
steps short and sweet for this sample app: 

1. Start Flash and, in the first screen that appears, choose the Flash file 
(Adobe AIR) item. 

Figure 3-9 shows the opening screen. 

2. From the Properties inspector, resize the document to 300 x 260px. 
The width and height properties are adjustable here. 

3. Add a textarea component onto the stage. 

I have my textarea sized at 250 x 200px. I positioned it at 23 (x) and 13 
(y). These sizes and positioning are appropriate for the scope of this app. 

4. From the Properties inspector, change the id of the textarea to 
taEditor. 




r the filename of the certificate file and click Save. 




With Flash CS4 



besiqxiinq the user interface 



5. 



Add two Button components onto the stage, positioning them side by 
side under the textarea. 
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Choose this item to start creating your app. 
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Figure 3-9: 

Creating an 
Adobe AIR 
application 
starts here. 



Open a Recent Iten 
% JotFiash.fla 

hello.fla 
| | Open... 



hJ Gottlng Started - 

B New features ■ 
D Resources » 

Don't show again 




Create New 

f| Flash File (ActionScript 3.0) 
f| Flash File (ActionSccipt 2.0) 
— ^ riash Tile (Adobe AIR) 
f| Flash File (Mobile) 
^ ActionScript Tile 

ActionScript C.munication Fil 

Flash JavaScript File 
~ Flash Project 



Create from Template 
f| Advertising 

Extend 
"i Flash Exchange ■ 



Adobe® Flash® CS4 Professional 

Find the latest tips, podcasts. and more 
in Adobe® Bridge Home. 



6. Label the first button Save and give it an id value of btnSave. 

7. Label the second button Close and give it an id value of btnClose. 

Figure 3-10 shows the stage after the components have been added and 
aligned. 



Figure 3-10: 

Ulofthe 
AIR app is 
ready. 
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Adding ActionScript code 

can attach AIR-based ActionScript code to the user interface by 
ough these steps: 

1. In the Timeline, select the first frame. 

The Timeline is at the top section of the Flash window. 

2. Right-click the frame and choose Actions from the pop-up menu. 
The Actions window is displayed. 

3. Add event listeners for the click events of the two buttons. 

Event listeners are functions you create that respond to events, in this 



case the clicking of the buttons. 

Type the following code in the Actions window: 




btnClose . addEventListener (MouseEvent . CLICK, 

closeHandler ) ; 
btnSave . addEventListener (MouseEvent . CLICK, 

saveHandler) ; 




Add the closeHandler ( ) function. 

Type the following code in the Actions window: 




function closeHandle: 
NativeApplicatioi 

} 


: (event : Event) : void { 

l. nativeApplication. exit ( 


) ; 


This function calls the AIR API to close the app. The 
NativeApplication . nativeApplication object is used to access 



several application level properties and methods, including exit ( ) . 

5. Add the saveHandler ( ) function. 

In the Actions window, enter the following code below the 
closeHandler ( ) function: 

function saveHandler (event: Event) :void { 

var file:File = File.desktopDirectory.resolvePath( "myjot.txt" ); 

var jot:String = taEditor . text; 

var stream: FileStream = new FileStream( ) ; 

stream. open( file, FileMode. WRITE ); 

stream. writeMultiByte ( jot, File . systemCharset ) ; 

stream. close ( ) ; 

} 
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The preceding code is some bona fide desktop-related code. This code 
provides you with the ability to programmatically save files to the 
's desktop. The file variable, which is an AIR-based File object, 
signed as a reference to the myj ot . txt file in the desktop folder of 
the user. The text contents of the textarea taEditor is assigned to 
the j ot variable. After that, the code opens a file stream, writes the con- 
tents of the jot file to it, and then closes the stream. 



Figure 3-11 shows the code added in the Actions window. 

Save your changes before continuing. Then you'll be ready to test the 
code you just added to the Flash project. 

6. Choose ControlOTest Movie to test your AIR app. 

Your AIR application will run under ADL in its own window. Try typing 
something in the textarea and then clicking Save. A myj ot . txt text 
file will be saved to your desktop. 
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Configuring and compiling 
P B 0 OfcSr^ application 



With the application design and coding now complete, you're ready to estab- 
lish the AIR settings and compile the application by walking through the fol- 
lowing steps: 

1. In the Properties inspector (with the Document selected), click the 
Edit button beside the AIR Settings label. 

The AIR - Application & Installer Settings dialog box, shown in Figure 3-12, 
is displayed. This dialog box is where you specify most of your application- 
level settings. 

2. If desired, modify the Application ID, Description, and Copyright. 

The Application ID needs to use a "reverse domain" syntax, which is kind of 
like a Web site address in reverse. Flash adds the com . adobe . example . 
prefix. Feel free to change to something specific to your context. 



Figure 3-12: 

AIR — 
Application 
& Installer 
Settings 
dialog box. 



AIR - Application & Installer Settings 



Application settings 
File name 
Name 

ID: 

Description 



Copyright: 



JotFlash 



JotFlash 



com.adobe.example.JotFlash 



Window style: System Chrome 



Icon: (Select Icon Images^ 



Advanced: f Settings.TT') 



' Use custom application descriptor file 



Installer settings 

Digital signature: Select a certificate to sign AIR file 



Destination: JotFlash. air 



— ipi 



/Users/rich/Development/airdev/Flash/jotFlash/ 
/Users/rich/Development/airdev/Flash/JotFlash/ 



( Help ) 



( Publish AIR File > ' Cancel ' f OK ^ 
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You can modify any of the settings that you want, or you can stay with 
the defaults. But the one task that's mandatory before you publish the 
lication is to create a self-signed digital certificate. 



the Set button next to the Digital Signature area. 



The Digital Signature dialog box appears (see Figure 3-13). 



Figure 3-13: 

The Digital 
signature 
dialog box. 



Digital signature 



Specify the digital certificate that represents the application publisher's identity. 
@ Sign the AIR file with a digital certificate 



Certificate: 
Password: 

[J Remember password for this session 
c^Timestamp 

C Prepare an AIR Intermediate (AIRI) file that will be signed later 



^ ( Browse.T~) ( Create. T~) 



"Cancel 



4. Click the Create button. 

The Create Self-Signed Digital Certificate dialog box appears (refer 
to Figure 3-8). 

5. Enter your name in the Publisher Name box. 

6. Enter a password in the Password and Confirm Password boxes. 

7. Click the Browse button. 

The Save dialog box appears. 

8. Enter the filename of the certificate file and click Save. 

The Create Self-Signed Certificate dialog box appears again. 

9. Click the OK button. 

The main AIR - Application & Installer Settings dialog box appears. 
10. Click OK. 

Flash compiles the application and creates the installable . air file 
for you. 
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In This Chapter 

Showing the relationship between Adobe AIR and JavaScript runtime environments 
Accessing the AIR API from within JavaScript and ActionScript 
Surveying the Adobe AIR API classes 



JLm nytime I travel around a new city or country, I'm always sure to throw 
¥ w a reliable map into my suitcase. Before I get out on city streets or coun- 
try roadways, I want to know what's there, how to get from point A to point 
B, and what the distances are between major spots of interest. As long as 
I study my trusty map on the plane trip there, I never feel that I'm going in 
blind, however foreign the locale may be to me. 

In the same way, when it comes to starting to develop applications with 
Adobe AIR, you can find it helpful to get a lay of the land, by surveying its 
application programming interface (API). Exploring the Adobe AIR API can 
give you a solid understanding on what AIR is built for and what you can do 
to create applications for this new platform. 

With that in mind, this chapter walks you through the API. First, however, I 
show you how you can make API calls from within your code. 

Exploring the Relationship between 
AlK and JavaScript Environments 

If you're an HTML/JavaScript developer, it's important for you to have a solid 
grasp of the impact of AIR on the scripting environment that you're already 
used to working within. After all, in a traditional Web page, the window is the 
top-level object that you interact with. The document and other DOM objects 
(as well as such browser-related objects as history and navigator) are all 
children of window. 
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The AIR runtime environment brings in more players: 
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NativeWindow object: The NativeWindow object is a container 
11 objects in a window and provides an interface to the native OS 
window. You can perform such functions as creating windows and modi- 
fying their look through the NativeWindow object. 

The HTMLLoader object: Inside the NativeWindow object, the 
HTMLLoader object serves as a container for HTML content. Each HTML 
window contains an HTMLLoader object. You can use this object to con- 
trol how HTML content is loaded and displayed. 

The JavaScript window object: The JavaScript window object keeps 
its traditional role as container for the DOM. However, it also pro- 
vides three properties that enable you to access the outer world of 
AIR: the current instance of the NativeWindow container (window. 
nativeWindow); the current instance of the HTMLLoader container 
(window. htmlLoader); and the rest of the AIR runtime API library 
(window . runtime). 

Because of security considerations, only top-level, sandboxed HTML 
documents have access to the nativeWindow, htmlLoader, and run- 
time properties. You can't access them from a document inside an 
if rame or frame. 

Figure 4-1 shows the relationships between the JavaScript and AIR objects. 



The HTMLLoader object has a window property, which is a pointer to the 
JavaScript window object inside of the JavaScript/DOM environment. This 
property isn't meant to be redundant and is actually not used when you're 
working inside JavaScript. Instead, ActionScript routines can access the 
JavaScript/DOM environment using HTMLLoader .window as a gateway. 



Figure 4-1: 

Relationship 
of AIR and 
JavaScript 
environ- 
ments. 



NativeWindow 



HTMLLoader 



window (JavaScript) 



nativeWindow 
htmlLoader 



DOM objects runtime 




Adobe AIR 
Runtime 
API 
Library 
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t of almost any AIR app is the interaction that takes place between 
the host scripting environment (JavaScript for HTML apps, ActionScript for 
Flex and Flash apps) and the Adobe AIR runtime. In this section, I provide an 
overview of how to call the API from inside JavaScript and ActionScript. 



Catting from JavaScript 



The Adobe AIR API is accessible from JavaScript through a special object 
called window, runtime. The runtime object, unique to AIR applications, 
is used as a gateway to access AIR runtime classes from your code. AIR's 
classes are logically organized into numerous ActionScript packages. Each 
package is represented as a property of runtime. For example, the flash 
package contains, among other things, the File class. So, if you wanted to 
create an instance of a File object, you could use the following declaration: 

var file = new window. runtime. flash. filesystem. File () ; 

That's the long way of doing things, however, and requires you to know the 
package name for any given object with which you wish to work. Fortunately, 
there's a better way. 



Adobe provides an "aliased" object named air that you can use to simplify 
the access calls and eliminate the requirement of specifying the package name 
inside the declaration. For example, using the alias definition, you can create a 
File instance using the following, much simpler, syntax: 



var file = new air. File (); 

To use aliases, include an external script library file called AiRAliases . j s 
inside your HTML file, and the world of air aliases opens to you: 

<script src= "AiRAliases . j s " /> 



A second benefit to using the AiRAliases . j s file is that the API syntax 
closely parallels the ActionScript syntax. The only difference is that you need 
to add the reference to the air object in JavaScript, but not in ActionScript. 
So, here's the JavaScript code to assign the application directory to a vari- 
able named dir: 



var dir = air . File . applicationDirectory; 
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The ActionScript code looks remarkably similar: 

r:File = File . applicationDirectory ; 
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You reference Adobe AIR API classes in ActionScript just as you do with 
other ActionScript packages and classes: Import the package using the 
import statement and then access the class in your code. For example, to 
use the File object, you need to import its package flash, f ilesystem. 
File. Here's some pseudo code to demonstrate: 

// first import the package. . . 
import flash. f ilesystem. File; 
// . . .and then use the object 
var file = new File ( ) ; 



Touring the Adobe AlR API 

When beginning to work with a new technology, one of the biggest hurdles 
developers often have is just understanding the lay of the land. In other 
words, it's hard to develop an application when you don't know exactly the 
tools you have to work with. 

The Adobe AIR API sports a healthy supply of classes that you can use to create 
desktop-based RIAs. The sections that follow take you on a round-the-world tour 
of the API to give you a basic understanding of what AIR runtime offers you as a 
developer and how you can interact with all aspects of the native operating sys- 
tems. The other chapters of the book give you additional details. 



Native OS Windows 

The Adobe AIR API enables you to create native OS windows, making your 
application look just like a standard Windows or Mac OS X application. 
You can also go your own route and create custom window styles and even 
window shapes. 

The following JavaScript function shows you how to create a new, empty 
window through the API: 

function createWindow ( ) { 

//Set up the initialization options 

var options = new air .NativeWindowInitOptions ( ) ; 
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options . systemChrome = air.NativeWindowSystemChrome. 
STANDARD ; 

ions . type = air. NativeWindowType . NORMAL; 
ions . transparent = false; 

//create the native window 

var nativeWindow = new air .NativeWindow (options ) ; 
nativeWindow . title = "The NativeWindows Are Restless"; 
nativeWindow. width = 400; 
nativeWindow. height = 3 00; 

/ /activate and show the new window 
nativeWindow. activate ( ) ; 

} 

The NativeWindowlnitOptions ( ) object enables you to set up certain 
options related to a window. You then use this options object when you 
create the NativeWindow instance. Basic window properties (title, 
width, and height) are assigned. Finally, the window is activated. 

I tell you much more about working with native windows in Chapter 7. 

Table 4-1 shows you the window-related classes of the API. 
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Table 4-1 Window Classes 



Class 


Description 


ActionScript 
Package 


[air . ] NativeWindow 


Creates and controls native 
desktop windows 


flash . display 
. NativeWindow 


[air . ] NativeWindow 
DisplayState 


Defines constants for the 
names of the window 
display states 


flash. display. 

NativeWindow 

DisplayState 


[air . ] NativeWindow 
InitOptions 


Defines the initialization 
options used to construct 
a new 

NativeWindow instance 


flash .display . 

NativeWindow 

InitOptions 


[air. ] NativeWindow 
Sy s t emChr ome 


Defines constants for the 

systemChrome 
property of the Native 
WindowInitOptions 
object 


flash. display. 

NativeWindow 

SystemChrome 



(continued) 



Part I: Airing It Out with Adobe AIR 



Table 4-1 (continued) 





Description 


ActionScript Package 


J Fa^r^n NativeWindow 


Defines constants for 


flash . display . 


Resize 


the possible values 


Native 




of the edgeOrCor- 


WindowResize 




ner parameter of the 






NativeWindow. star- 






tResize ( ) method 




[air . ] Native 


Defines constants for 


flash . display . 


WindowType 


the type property of the 


NativeWindow 




NativeWindow 


Type 




InitOptions object 





'G 



Local (ites 

The AIR API lets you work with files and folders with all the usual capabili- 
ties: You can create files and directories, copy and move files around on the 
user's hard drive, and display native OS Open and Save dialog boxes. What's 
more, you can read and write files from disk or URL (any Internet location). 

Following is an example of local file and directory access using JavaScript. 
The following function copies a directory to another location and then copies 
a text file to the user's desktop: 

function backup ( ) { 

// Copying user's folder for backup 

var userFolder = air .File. documentsDirectory. 

resolvePath( "Giggles" ) ; 
var backupFolder = air .File. documentsDirectory. 

resolvePath ( "Giggles . backup" ) ; 
userFolder . copyTo (backupFolder) ; 

// Copying a file 

var readme = air .File. documentsDirectory. 

resolvePath ( "Giggles/giggles_readme . txt " ) ; 
var readmeDesktop = air. File. desktopDirectory. 

resolvePath ( "readme_now_or_else.txt" ) ; 
readme . copyTo (readmeDesktop, true) ; 

In this code, the userFolder variable is assigned the Giggles folder, 
which is a subfolder inside the user's documentsDirectory (the user's My 
Documents directory in Windows or Documents directory in Mac OS X). Note 
the resolvePath ( ) method, which allows you to get a path (Giggles) that 
is relative to another path (Documents directory). The backupFolder 
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variable is assigned to a backup directory. The copyTo ( ) method then 
ies the Giggles directory to the backupFolder. 



nd part of the function assigns the giggles_readme . txt file to the 
readme variable, and readmeDesktop is a variable assigned to a file on the 
user's desktop folder. The copyTo ( ) method copies the readme file to the 
new location. 

See Chapter 10 for more about files and folders. 
Table 4-2 lists the file-related classes of the AIR API. 



Table 4-2 File Classes 



Class 


Description 


ActionScript Package 


[air . ] File 


Pointer a path to a file 


flash. f ilesystem. 




or directory 


File 




[air. ] 


Used to read and write 


flash. f ilesystem. 


FileStream 


files 


FileStream 




[air. ] 


Defines constants used 


flash. f ilesystem. 



FileMode when opening files with FileMode 



FileStr 


•e 


am 




[air. ] 
FileFilter 


Defines what files on 
the user's system are 


flash . net . Fi 


leFilter 



browse dialog box 



Menus 

Menus — both top level and right-click contextual menus — are one of the 
fundamental UI building blocks of any Windows or Mac OS X application. The 
Adobe AIR API provides capabilities to create robust native menus in your 
application. The following JavaScript code creates a top-level File menu with 
a single Open item: 

// Create root menu 

var rootMenu = new air .NativeMenu () ; 
// Add a File menu item 

var fileMenuItem = rootMenu. addltem( "File" ) ; 

// Create menu and assign it as the submenu 
var fileSubmenu = new air. NativeMenu ( ) ; 
fileMenuItem . submenu = fileSubmenu; 
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/,/ Add Open item 

leOpenltem = f ileSubmenu . addltem ( "Open" 



// Add event handler 
f ileOpenltem. addEventListener ( air . Event . SELECT, 
f ileOpen) ; 

/ / If running on Windows , add as window menu 
if (air . NativeWindow . supportsMenu ) { 
nativeWindow . menu = rootMenu; 

} 

// If running on Mac OS X, add as application menu 
if (air .NativeApplication. supportsMenu) { 
air .NativeApplication. menu = rootMenu; 

} 



// Handler for the File Open menu item 
function fileOpenO { 

alert ("An open file can do no harm, so they say."); 

} 



The rootMenu NativeMenu instance serves as the container for the sub- 
menu and menu items of this example. A File menu item (f ileMenuitem) is 
added to the rootMenu and then a submenu is created and assigned to it. 
Next, the Open menu item is added to the f ileSubmenu. 

To have the menu item do anything when a user selects it, you need to add 
an event handler to it, which I do with the addEventListener ( ) method. 
It tells AIR to execute the f ileOpen ( ) function (defined at the end of the 
code) when the f ileOpenltem is selected. 

The final step is to assign the rootMenu to the application as a top-level 
menu. However, Windows and the Mac handle top-level menus differently. A 
top menu under Windows is contained by the window, whereas under Mac 
OS X, the top menu becomes the system-wide application menu at the top of 
the screen. Therefore, before assigning it as a window or application menu, 
the code checks to see whether that capability is supported at runtime by 
checking the result of the supportsMenu property. 



See Chapter 8 for more of the scoop on menus. 



Table 4-3 highlights the menu-related classes as well as other Ul-related 
classes in Adobe AIR. 
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User Interface Classes 






Description 


ActionScript Package 


[air\ ] NativeMenu 


Defines a native 
menu (Application, 
Window, Dock icon. 
System tray. Context, 
Pop-up) 


flash. display. 
NativeMenu 










[air.] 

Nat iveMenuI tern 


Represents a menu 
item 


riasn. aispiay . 
Na t i veMenu I t em 


[air . ] Screen 


Defines properties to 
indicate the display 
screens available 


flash. display. 
Screen 




Represents an icon 


flash. desktop . 
Icon 


[air . ] Docklcon 


Represents a Mac OS 
X style dock icon 


flash. desktop. 
Docklcon 


[air. ] 

Interactive I con 


Abstract base class 
for icons associated 
with an application 


flash. desktop. 
Interactivelcon 


[air . ] 


Defines constants for 


flash. desktop. 
Notif icationType 


Notif icationType 


the priority param- 
eter of Docklcon. 
bounce ( ) and the 
type parameter of 

Nat i veWindow . 
notifyUser ( ) 


[air . ] 

SystemTraylcon 


Represents a 
Windows system tray 
icon 


flash. desktop. 
SystemTraylcon 


[ air . ] Loader 


Loads SWF files or 


flash. display . 




image (JPG, PNG, or 
GIF) files 


-Loader 




[air . ] Bitmap 


Represents a bitmap 
image 


flash. display. 
Bitmap 


[air . ] BitmapData 


Provides a means to 
work with the pixel 
data of a bitmap 


flash. display. 
BitmapData 
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Inter-apptication data exchange 



e AIR API taps into the familiar inter-application exchange 
'sm in Windows and Mac OS X, what is ubiquitously known as the 
Clipboard. You can use the Clipboard's data-exchange capabilities through 
Copy and Paste routines as well as through drag-and-drop. Tables 4-4 and 4-5 
list the Clipboard and drag-and-drop classes of the API. 

The following JavaScript example shows you how to copy a piece of text to 
the Clipboard: 

function copyMe ( ) { 

var txt = "This little text went to the market."; 
air . Clipboard. generalClipboard. clear ( ) ; 
air . Clipboard. generalClipboard. setData (air . 

ClipboardFormats . TEXT_FORMAT , txt) ; 

} 



The clear ( ) method of the Clipboard object is used to remove existing 
contents from the Clipboard. Then, the setData ( ) method adds the txt 
String variable to the Clipboard as plain text. 

Chapter 9 dives into more detail on working with the Clipboard and 
drag-and-drop. 



Table 4-4 


Clipboard Classes 




Class 


Description 


ActionScript 
Package 


[air . ] Clipboard 


Defines a container for trans- 
ferring data and objects via the 
Clipboard and drag-and-drop 


flash. desktop. 
Clipboard 


[air . ] Clipboard 


Defines constants for standard 


flash. desktop. 


Formats 


data formats used with the 
Clipboard 


Clipboard 
Formats 


[air . ] Clipboard 
Trans ferMode 


Defines constants for the 
transf erMode parameter 
of the Clipboard. get- 
Data ( ) method 


flash. desktop. 
Clipboard 
Transf erMode 
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Drag-and-Drop Classes 


^em?^ NativeDrag 


Description 


ActionScript Package 


Manager 


Coordinates drag-and-drop 
operations 


flash . desktop . 
NativeDragManager 


[air . ] NativeDrag 
Options 


Declares the drag-and-drop 
actions that are relevant to 
a drag operation 


flash . desktop . 

Native 

DragOptions 


[air. ] NativeDrag 
Actions 


Defines constants for the 

NativeDragManager . 
dropAction property 


flash . desktop . 
Na t iveDr agAc t i ons 



Multimedia 

Adobe AIR provides various media-related classes (see Table 4-6) to work 
with audio files as well as to interact with such hardware as the system 
microphone or camera. You can use these multimedia capabilities to add 
sound effects to your app or develop a full-fledged video, audio, and camera 
capture app. 

The following JavaScript code shows you how to play a sound: 

var sndFile = new air .URLRequest ( "ping. mp3 ") ; 
var snd = new air .Sound (sndFile ) ; 
snd.play ( ) ; 

The sndFile variable references the ping .mp3 sound file. An instance of a 
Sound object is created using that sndFile variable, and then it is played 
using the play ( ) method. 

Flip to Chapter 13 for the full scoop on working with audio. 



Table 4-6 


Media Classes 




Class 


Description 


ActionScript Package 


[air. ] ID3lnfo 


Provides proper- 


Flash .media . 




ties representing 


ID3lnfo 




ID3 metadata for an 






MP3file 
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Description 


ActionScript Package 




^ Sound 


Provides access to 

cm inn i^anahilitiDC 
oUUIIU \j a Ucl Ul II Llco, 

such as playing an 
audio file 


Flash .media . 
Sound 


[air . 


] SoundChannel 


Pnntrn c cnimH in 
LiUIILIUlo oUUIIU III 

an app (a sound is 
assigned to a sound 
channel) 


Flash . media . 
SoundChannel 






[air . ] SoundLoader 
Context 


Used to perform 
security checks for 
files that load sound 


Flash .media . 

SoundLoader 

Context 


[air . 


] SoundMixer 


PrnwiHoc rt 1 n rt Q 1 

nuviUcb yiuudi 
sound and mixing 
control 


flash . media . 
SoundMixer 


[air. ] 

SoundTransf orm 


Provides properties 

Tn r \ I n 1 1 1 m Q !inn nan 
IUI VUlUMIc dllu pdll 

control 


flash .media . 
SoundTrans form 


[air . 


] Microphone 


Captures audio 


flash . media . 






from a microphone 

nttprhpH tn thp 

computer 


Microphone 


[air . 


] Video 


Captures video from 
a video camera 
attached to the 
computer 


flash . media . 
Video 


[air . 


] Camera 


Captures images 
from a digital 
camera attached to 
the computer 


flash . media . 
Camera 













Keyboard and mouse 

The AIR API provides access to the keyboard and mouse of the system run- 
ning your application. You can use it to trap for keyboard or mouse events. 
Here's an example of how to use JavaScript to listen to keyboard input and 
then add custom functions when the user clicks the left, right, top, and down 
arrows. The first thing is to call addEventListener ( ) to listen for the key- 
Down key in the initialization routine of the app: 
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window . nativeWindow. stage . addEventListener ( "keyDown" , onKe 
y) ; 



It, when any key is pressed, a function called onKey ( ) is triggered, 
which follows: 



function onKey (event) { 

switch (event . keyCode) { 
case air .Keyboard. LEFT : 

alert ("Turn left to surf!"); 
break; 

case air .Keyboard. RIGHT : 

alert ("Turn right to get chowda ! " ) ; 

break; 
case air .Keyboard. UP : 

alert ("Go up for Hockey!"); 

break; 

case air . Keyboard . DOWN : 

alert ("Go down for great TexMex! " ) ; 

break; 
default 

break; 

} 

} 



In this routine, the switch statement evaluates the keycode of the key 
pressed. If the keycode matches the air . Keyboard . LEFT, air . Keyboard . 
RIGHT, air . Keyboard . UP, and air . Keyboard . DOWN, an alert ( ) mes- 
sage box displays. Otherwise, the key passes through without incident. 

Table 4-7 shows the classes related to the keyboard and mouse. 



Table 4-7 


User Interaction Classes 


Class 


Description 


ActionScript Package 


[ air . ] Keyboard 


Defines constants 
representing keyboard keys 
and provides an interface to 
the keyboard 


flash . ui . 
Keyboard 


[air . ] Key 
Location 


Defines constants on the 
location of a key pressed on 
the keyboard 


flash . ui . Key 
Location 


[air . ] Mouse 


Allows you to show/hide the 
mouse pointer 


f lash.ui .Mouse 
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te database engine is built inside the Adobe AIR runtime. The AIR 
r ides a host of database classes (see Table 4-8) for storing and 
working with local data. You can use the database to store user data or 
application-specific data. 

Consider the following JavaScript example, which uses the API to connect to 
a database named chuckles . db and insert a new record into the contacts 
table: 

var conn = new air . SQLConnection ( ) ; 

var dbFile = air. File. documentsDirectory . resolvePath 

( "chuckles .db" ) ; 
// open the database 

conn.open(dbFile, air . OpenMode . UPDATE) ; 

// add the customer record to the database 

var insertStmt = new air . SQLStatement () ; 

insertStmt . sqlConnection = conn; 

insertStmt . text = 

"INSERT INTO contacts (firstName, lastName, phone) " + 
"VALUES ('Rocky', ' Burky ' , '719-555-1212')"; 

insertStmt . execute ( ) ; 

conn. close ( ) ; 

In this example, a connection is established to the chuckles . db database 
file and opened in update mode. The conn variable is used to represent the 
connection. 

The insertStmt variable is an instance of SQLStatement and is used to 
send a SQL statement to the database. After that statement is assigned to the 
text variable, its execute ( ) method is called. 



Table 4-8 


Database Classes 




Classs 


Description 


ActionScript 






Package 


[air . ] Encrypted 


Manages getting and 


flash . data . 


LocalStore 


setting objects in the 


Encrypted 




encrypted local data store 


LocalStore 
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Class Description ActionScript 

• Package 



DropBo 



JKS 

SQLCol 1 a t i onType 


Defines constants for the 

def aultCo llation 
Type parameter of the 
SQLColumnSchema 
constructor, as well as the 

SQLColumnSchema . 
def aultCollat ion- 


flash. data. SQL 
CollationType 




Type property 






[air . ] SQLColumn 
NameStyle 


Defines constants for the 

SQLConnection . col- 
umnNameStyle property 


flash. data. SQL 

ColumnName 

Style 


[air. ] SQLColumn 
Schema 


Provides info for the speci- 
fied column within a data- 
base table 


flash. data. SQL 
ColumnSchema 


[air . ] SQLConnection 


Manages the creation of 
and connection to local 

^fll H ntn ha cd f il pq 
JUL UdldlJcloc lllco 


flash . data . 
SQLConnection 


[air . ] SQLError 


Provides details about a 
failed database operation 


flash . errors . 
SQLError 


[air . ] SQLError 
Event 


Triggered by 

SQLConnection or 
SQLStatement when a 
database error occurs in 
asynchronous execution 
mode 


flash. 
SQLErr 


events . 
orEvent 


[air . ] SQLError 


Defines constants for the 


flash. 


errors . 



Operation SQLError . operation SQLError 

property Operation 

[air . ] SQLEvent Dispatched when a flash, events. 

SQLConnection or SQLEvent 
SQLStatement instance 
completes successfully 



[air . ] SQLlndexSchema Provides info for the speci- flash. data. 

fied index in a database SQLlndexSchema 
table 



[air . ] SQLMode 


Defines the constants for flash . data . 




the openMode parameter SQLMode 




of the SQLConnection . 




open ( ) and SQL 




Connection . 




openAsync ( ) methods 
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Table 4-8 (continued) 




Description 


ActionScript Package 


y falr\1 SQLResult 


Provides access to 
data returned by a 

SQLStatement instance 


flash . data . 
SQLResult 


[air . ] SQLSchema 


Serves as base class for 
schema for database 


flash . data . 
SQLSchema 




objects 






r a "i T~ 1 

SQLSchemaResult 


Provides info from a call to 

the SQLConnection. 
loadSchema ( ) method 


flash. data. SQL 
SchemaResult 


[air . ] SQLStatement 


Execute a SQL statement 
against a local SQL data- 
base that is open through 

a SQLConnection 
instance 


flash. 
SQLSta 


data . 
tement 


[air . ] SQLTableSchema 


Defines the specified table 
in a database 


flash . data . 
SQLTableSchema 


[air. ] SQL 
T 1 t Pi ti <=5 r* t" "i on 


Defines constants for the 
option parameter of 


flash. data. SQL 
Transaction 


LockType 


the SQLConnection. 
begin ( ) method 


LockType 


[air . ] SQLTrigger 
Schema 


Defines the specified trig- 
ger within a database 


flash. data. SQL 
Trigger Schema 


[air . ] SQLUpdateEvent 


Dispatched by a 
SQLStatement object 
when data changes as a 
result of a SQL statement 
or trigger 


flash. 
SQLUpd 


events . 
ateEvent 


[air . ] SQLViewSchema 


Provides info for the 


flash 


. data . 




specified view within a 
database 


SQLVi ewfa enema 



Communication 

Adobe AIR is all about creating RIAs — rich internet applications. Not surpris- 
ingly, then, its API sports a healthy supply of internet communication-related 
classes and functions, as shown in Tables 4-9 and 4-10. You can use this part 
of the API to do simple tasks, such as calling a URL: 
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url = "http://www.dummies.com"; 
urlRequest = new air . URLRequest (url ) 
vigateToURL (urlRequest ) ; 



In this JavaScript code, the url variable is assigned the value of a Web site. 
Not just any site, mind you. This variable is then passed as a parameter when 
a URLRequest instance is created. The navigateToURL ( ) method is then 
called using this variable as a parameter. 

Chapter 12 tells you more about network connectivity. 



Table 4-9 Network Connection Classes 



Class 


Description 




ActionScript Package 


[ air . ] URLLoader 


Downloads data from 
a URL as text, binary 
data, or URL-encoded 
variables 


flash.net 
URLLoadei 




[air . ] URLLoader 
DataFormat 


Defines values to 
specify how down 
loaded data is 
received 


- 


flash . net . 

URLLoaderData 

Format 










[air . ] URLRequest 


Captures data in a 
single HTTP request 


flash.net 
Request 


: .URL 


[air . ] URLRequest 
Defaults 


Defines static prop- 
erties for defining 
default values for 
URLRequest class 


flash.net 
URLReques 
Defaults 


it 


[air. ] 

URLRequestHeader 


Encapsulates a single 
HTTP request header 
in the form of a name/ 
value pair 


flash.net. 
URLRequestHeader 


[air. ] 

URLRequestMethod 


Determines whether 
the URLRequest 
object should use 
POST or GET method 
when sending data to 
a server 


flash . net . 
URLRequestMethod 


[air. ]URL 
Stream 


Provides low-level 
access to download- 
ing URLs (compared to 
URLLoader which 
is used when a file is 
completed) 


flash . net . 
URLStream 
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Table 4-9 (continued) 


^ ] URL 


Description 


ActionScript Package 


Variables 


Allows you to transfer 
variables between an 
app and a server 


flash . net . 
URLVariables 


[air . ] Socket 


Establish a socket 
connection and read/ 


flash . net . Socket 




write raw binary data 






[air. ]XML 
Socket 


Establish a socket 
connection to commu- 
nicate with a server 
computer identified 
by an IP address or 
domain name 


flash.net 
XMLSocket 




[air . ] Responder 


Used by 

NetConnection . 
call ( ) to handle 
return values from the 
server 


flash.net 
Respondei 




[air . ] Obj ect 


Defines serializa- 


flash.net 
Obj ectEnc 


:oding 


Encoding 


tion settings in 
classes that serialize 
objects to work with 
legacy versions of 
ActionScript. 


[air . ] NetStream 


Defines a one-way 
streaming connec- 
tion between app and 
Flash Media Server 


flash.net 
NetStrean 





Table 4-10 


URL-Related Functions 


Function 


Description 


ActionScript Package 


[air. ] 


Opens a URL in the 


flash . net . 


navigate- 


default system browser 


navigateToURL 


ToURL ( ) 






[air. ] 


Sends a URL request 


flash . net . sendToURL 


send- 


to server (ignores 




ToURL ( ) 


response) 
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In addition to using remote network connections, such as URLs or app serv- 
ers, you can use the AIR API to connect to other AIR applications, other 
U^vithin the same AIR app, and even Flash media running inside the 
2h(see Table 4-1 1). For example, if you want to set up your app to con- 
with another app in the same domain, you write the following: 

// Create local connection 

var clientConn = new air . LocalConnection ( ) ; 
clientConn . connect ( "rockdude" ) ; 

// Create object that will be called remotely 
var clientCommunicator = new Object (); 

// 

clientCommunicator . talkToMe = function () { 
air . trace ( "Hey, you rock, dude!"); 
} 

clientConn . client = clientCommunicator; 

This code creates a LocalConnection object named lc and then defines a 
custom JavaScript object named clientCommunicator. The client prop- 
erty of lc is then assigned to the custom object. 

A second application could call the talkToMe ( ) method by establishing 
a local connection with the rockdude connection and then specifying the 



method in the send ( 


) method: 










var serverConn = new air . LocalConnection () ; 
serverConn . connect ( " rockdude " ) ; 





serverConn . send ( " rockdude " , " talkToMe " ) ; 



DropBoOK 

verse 



Table 4-11 


Application Communication Classes 


Class 


Description 


ActionScript 
Package 


[air . ] 


Establish a connection to 


flash . net . Local 


LocalConnection 


communicate between two 
files (SWF<->HTML, SWF<- 
>SWF, etc.) 


Connection 


[air. ]NetConnection Defines a bidirectional 

connection 


flash.net .Net 
Connection 


[air . ] SharedObj ect 


Enable data sharing 
between multiple files/ 
objects on local computer 
or server 


flash . net . 
Shared 
Obj ect 


[air . ] SharedObj ect 
FlushStatus 


Defines return values 

for SharedObj ect . 
flush ( ) method 


flash . net . 
Shared 
ObjectFlush 
Status 
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The 5 th Wave By Rich Tennant 




" Okay antidote, antidote, -what vrould an antidote 
icon look like? You knovr, I still haven't got this 
desktop the vray I'd like it." 



DropBooks 













In this part . . . 

■ he introductions are over. It's time to get down to 
w business and focus on application design. You focus 
in this part on the basics of UI design using HTML and 
CSS, and on and creating windows and menus from your 
app. You then explore how to work with menus and icons. 















Chapter 5 
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as Building Blocks 



In This Chapter 

Understanding the HTMLLoader object 
Exploring the WebKit CSS extensions 
Drawing with the canvas element 



f 

■ n Chapter 2, 1 walk you through the basics of creating an HTML-based AIR 
«C application. Using that process as a guide helps you realize that working 
with the content and presentation layer in AIR is nearly identical to designing 
a traditional Web application. HTML and CSS work the same way. The HTML 
DOM is still the way in which you access and manipulate the document 
through scripting. JavaScript works much the same way as it does within a 
normal Web page. 

However, AIR's HTML environment gives you some additional capabilities 
(such as extended styles or the canvas element) that you should understand, 
regardless of whether you're creating an HTML-based application or even 
integrating an HTML window inside your Flex or Flash application. 

In this chapter, you explore the familiar world of HTML, but do so within this 
new AIR environment. 



Working With HTMLLoader 

Whether you're creating an HTML-based AIR application or displaying 
HTML content in your Flex or Flash app, each HTML document you display 
is contained in its own HTMLLoader object. The HTMLLoader manages the 
behavior and aspects of the appearance of the HTML display. As you work 
through this section, you explore how to access HTMLLoader and display 
content in it. 
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Accessing and sizing the HTMLLoader 



L application, an instance of the HTMLLoader object is created 
cally for you. You can access this HTMLLoader instance by accessing 
the htmlLoader property of the JavaScript window object: 

window . htmlLoader 



When you're creating an HTML-based app, you can set the initial size of the 
application through the application descriptor XML file. However, you can 
also set the size through the width and height of the HTMLLoader, like so: 



window . htmlLoader .width = 500; 
window . htmlLoader . height = 400; 



In a Flex or Flash application, you need to explicitly create an instance of 
HTMLLoader by using the following code: 

var htmlLoader : HTMLLoader = new HTMLLoader ( ) ; 
var urlRequest : URLRequest = new URLRequest ( " local_help . 
html " ) ; 

htmlLoader . width = myPanel . stageWidth; 
htmlLoader . height = myPanel . stageHeight ; 
htmlLoader . load (urlRequest ) ; 
myPanel . addChi Id (htmlLoader ) ; 



The htmlLoader instance uses urlRequest to specify the URL to open 
using load ( ) . Also, notice that I set the dimensions of htmlLoader. That's 
because when you're creating an HTMLLoader in ActionScript, the width 
and height properties are 0, so you need to specify them. 



Loading HTML content 

HTMLLoader allows you to load HTML content using the load ( ) and 
loadStringO methods. The load ( url) method loads the specified URL. 
For example: 

window . htmlLoader . load ( "http : / /www . dummies . com" ) ; 

You can also use the loadString (htmlContent) method to load HTML 
content through a string parameter. Here's an ActionScript example: 
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var htmlLoader : HTMLLoader = new HTMLLoader ( ) ; 
r htmlText : String = getHTMLContent ( ) ; 
ader . loadString (htmlText) ; 



Setting the transparency of a Window 

One of the visual settings that many HTML developers will want to consider 
when creating an AIR app is the ability to make the background of the 
window transparent — something that can't be done with a traditional 
Web app. 

However, HTML developers who want to set a transparent background for 
their applications can become perplexed when they try to do so. It is not so 
intuitive. When you forget about HTMLLoader, the natural inclination is to 
set the transparency property of the application descriptor file to false 
and then set the CSS background to transparent. But, as you'll discover if 
you try to do both of those things, that's not enough. The reason is that the 
HTMLLoader container has an opaque background by default. 

Therefore, you need to set the paintsDef aultBackground to false: 

window . htmlLoader . paintsDef aultBackground = false; 

The HTML document itself does not support alpha blending (other than by 
using a blended PNG graphic as a background- image). Technically, the 
HTMLLoader does have an alpha property that you can use for alpha 
blending, although this property is not used much in HTML applications. 



Launching a URL in the 
default system browser 

When you click a link inside of an HTML document or assign a URL to 
window, location, the requested page will be displayed inside the same 
HTMLLoader object. However, if you want to launch the URL in the default 
system browser (typically Internet Explorer, Firefox, or Safari) instead, then 
you can set the navigatelnSystemBrowser property to true: 

window. htmlLoader .navigatelnSystemBrowser = true; 
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By now, you can see how similar the behavior of HTMLLoader is to a 
browser. It should not be much of a surprise, therefore, that the HTMLLoader 
is also responsible for maintaining a history list for the URLs that are 
accessed inside of it. 

When a URL is added to the history list, it is stored as a HistoryListitem. 
You can then use the HTMLLoader history-related properties and methods, 
as listed in Table 5-1, to work with a HistoryListitem collection to create 
a virtual browser-like experience inside your application. 



Table 5-1 HTMLLoader History-Related Members 



Member 


Description 




historyBack ( ) 


Goes back in the history list. 




historyForward ( ) 


Goes forward in the history list. 




historyGo (x) 


Goes forward or backward x number 


of spaces. 


getHistoryAt ( index) 


Returns an HTMLListitem element at index 
position in the list. 


HistoryLength 


Gives the length of the history list. 





HistoryPosition Shows the current position in the history list. 



The following code shows an example of how you can use the history-related 
functionality in your app: 

function back ( ) 
{ 

window . htmlLoader . historyBack ( ) ,- 

} 

function forward () 
{ 

window. htmlLoader .historyForward ( ) ; 

} 

function getltemlnf o ( idx) 
{ 

item = window. htmlLoader . getHistoryAt ( idx) ; 

alert ("URL:" + item.url + 

" Title: " + item. title + 

" Original URL: " + item . originalURL) ; 

} 



Chapter 5: Using HTML and CSS as Building Blocks 



lakina Advantage of WebKit Extensions 

3 I ' ^) ^^H^^u create an HTML-based application in Adobe AIR, you finally have 
a area 



a great excuse to forget about all the cross-browser compatibility issues that 
continually dog Web developers. Because you're developing for the browser 
embedded inside the AIR runtime, your only requirement is to ensure that 
your page looks and performs properly with WebKit. What's more is that 
although WebKit is standards based, it also features some nonstandard 
extensions that you can feel free to take advantage of as you develop your 
interface. 

Use this section to help you identify several little secret compartments in 
that Web developer toolbox of yours. 

Table 5-2 lists the major extensions to CSS that you can use in your Adobe 
AIR applications. 



Table 5-2 



Major WebKit Extensions to CSS 



CSS Property Name 



Description 



-webkit- 


-background-size 




Specify the size of a 
background image. 








-webkit- 


-border-horizontal -spacing 


Horizontal component of 
the border spacing. 


-webkit 


-bor der- vertical - 


spacing 


Vertical component of the 
border spacing. 


-webkit- 


-border-radius 




Define the rounding radius 
for the four corners of a 
box. 


-webkit 
-webkit 


-border-bottom- left-radius 
-border-bottom- right -radius 


Define radiusfor one of the 
four corners of a box. 


-webkit 


-border- top- lef t- 


radius 




-webkit- 


-border- top-right 


-radius 




-webkit- 


-line-break 




Line break rule to use for 
Chinese, Japanese, and 
Korean (CJK) text. 


-webkit- 


-margin-bottom-collapse 


Determines how the 



bottom margin of a table 
cell collapses. 



(continued) 
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perty Name 



it-margin- col lapse 



-webkit-margin-start 



-webkit-margin- top- col lapse 



-webkit-nbsp-mode 



-webkit-padding- start 



-webkit- text -security 



-webkit-user-drag 



-webkit-user-modif y 



-webkit-user- select 



Description 



Determines how the top 
and bottom margins of a 
table cell collapses. 



Width of the starting 
margin (usually leftside) 



Determines how the top 
margin of a table cell 
collapses. 



Behavior of nonbreaking 
spaces within the enclosed 
content. 



Width of the starting 
padding (typically left side) 



-webkit-rtl- 


-ordering 


Overrides the default 
handling of mixed left-to- 
right and right-to-left text. 


-webkit-text 


;-f ill-color 


Text fill color. 





Replacement shape to use 
in a password field. 



Use when you need to 
override the automatic 
drag behavior. 



Indicates whether the 
content of an element can 
be edited. 



Indicates whether a user 
can select the content of 
an element. 



Although some of the extensions are fairly obscure, there are a few jewels to 
take advantage of, as described next. 



Creating rounded rectangles 

The -webkit-border-radius and its related properties allow you to define 
the radius of the border of a block level element. You can use this extension 
to easily create rounded rectangles rather than resort to image-based 
corners. The following example creates rounded corners on the top of a div 
element, but keeps the bottom corners square: 
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webkit-border-bottom-lef t-radius : Opx; 
webkit-border-bottom-right-radius : Opx; 
it-border-top-left-radius : 15px; 
it-border-top-right-radius : 15px; 



Figure 5-1 shows the result. 



Figure 5-1: 

Rounded 
rectangles 
made possi- 
ble through 
a WebKit 
extension. 



Appl C 




See Chapter 2 for another example of using -webkit-border-radius in an 
HTML app. 



Making links into push buttons 

The -webkit-appearance property is a WebKit extension that is designed 
to change the appearance of an HTML element and transform it into a variety 
of different UI controls. Adobe AIR supports -webkit-appearance : push- 
button, which can enable you to easily turn a link or other element into a 
push button. To demonstrate, begin with a link assigned to a class named 
special: 

<a href = "http :/ /www. dummies . com" class= " special " >Visit Our 
Home Page</a> 

The a . special style can then be defined as follows: 

a . special 
{ 

display: block; 
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width: 180px; 
font-size: 14px; 

-weight: bold; 
-height: 3 0px; 
color: #000000; 
text-decoration: none; 
text-align: center; 
margin: 15px auto; 
-webkit-appearance : push-button; 

} 



The -webkit-appearance : push-button property transforms the 
appearance of the a link into a push button. The remaining properties set the 
formatting and positioning of the element. 

Figure 5-2 shows the transformation when the AIR application runs. 




Setting alpha Values 

WebKit enables you to set an alpha value when declaring an RGB color with 
the new rgba ( ) declaration. Using rgba ( ) , you can add translucent color 
overlays using CSS and avoid transparent PNGs or GIFs. The syntax for the 
declaration is as follows: 
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and b values are integers between 0-255 that represent the red, 
d blue values. The a is the alpha value between 0 and 1 (0 . 0 is 
transparent, 1 . 0 is fully opaque). For example, to set a green background 
with a 40 percent transparency value, you use the following: 



background: rgba(0, 2 55, 0, 0.4); 

The following example shows five div elements, each with a different alpha 
value for the background-color. The text-shadow property also uses 
rgba. Here is the full source code: 

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http:// 
www. w3 . org/TR/html4/ strict . dtd" > 

<html> 
<head> 

<meta http-equiv=" Content-Type" content= " text /html ; 

charset=iso-8859-l" /> 
<title>WebKit CSS Extensions</title> 

<script type= " text/ j avascript " src="AIRAliases . j s " ></ 
script> 

<style> 

div . blockHead 

{ 

font-size: 46px; 
text-align: center; 
color: #ffffff; 

text-shadow: rgba ( 0 , 0 , 0, 0.7) 0 lpx 0; 
line-height: 7 6px; 

} 

</style> 

</head> 

<body> 

<div class= "blockHead" style= "background-color : rgba(0, 0, 

0 , 0.2);" ><span>20%</spanx/div> 
<div class= "blockHead" style= "background-color : rgba(0, 0, 

0 , 0.4); "><span>40%</spanx/div> 
<div class= "blockHead" style= "background-color : rgba(0, 0, 

0 , 0.6);" ><span>60%</spanx/div> 
<div class= "blockHead" style= "background-color : rgba ( 0 , 0, 

0 , 0.8);" ><span>80%</spanx/div> 
<div class= "blockHead" style= "background-color : rgba ( 0 , 0, 

0, 1.0) ; " ><span>100%</spanx/div> 

</body> 
</html> 



Figure 5-3 shows the effect of this code when the application runs. 



Part II: AIR Application Design 



ft n o 



►Books 



WebKit CSS Extensions 



40% 



Figure 5-3: 

The varying 
alpha values 
for these 
divs form a 
gradient. 



Dmutiny Graphics on the HTML Ccmtfas 

Although ActionScript developers have the ability to draw graphics on a 
canvas in their Web or AIR applications, HTML developers have never had 
this same level of programming power. You can use JavaScript to create or 
animate DOM elements, but not to create lines or other shapes from scratch. 
However, WebKit supports the HTML canvas element that defines a drawing 
region in the document that you then draw on using the WebKit Canvas API. 

Canvas drawing can be intimidating because you need to draw on-screen by 
defining a series of x,y coordinates for lines and rectangles. As you begin, I 
recommend using a piece of old fashioned graph paper to sketch out the 
shapes in a grid. 



Addinq a canVas 

You can think of a canvas as a flat, two-dimensional surface that has a 
default origin (0,0) in the top-left corner. As in an HTML document, all the x,y 
coordinates that you specify are relative to this position. 

To define a canvas in your JavaScript code: 

<canvas id="whiteboard" style="width:350px;height:350px; "/> 

You can place as many canvas elements on a page as you want. Each just 
needs to have its own unique id value. 
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You can now draw inside the surface region using JavaScript. The following 
sections show you how. 

DropBooks 

Getting a context 

The canvas element serves as the container for your drawing area, but 
you don't actually work with the canvas to do so. Instead, you work with 
something called a 2d context object. All the drawing properties and methods 
that you work with are called from the context object. 

To get a context object to work with, you call the canvas element's 
getContext ( ) method: 

var canvas = document. GetElementByld ( "canvasElement" ) ; 
var context = canvas . getContext (" 2d" ) ; 



Dmutiny a rectangle 

In order to draw a rectangle onto a canvas, you can use one of three methods 
of the context object: 

W context . f illRect (x,y, w, h) draws a filled rectangle. 

context . strokeRect (x, y , w, h) draws a rectangular outline. 

context . clearRect (x, y, w, h) clears the specified rectangle and 
makes it transparent. 

For example, suppose you'd like to draw a rectangular outline and a solid box 
inside it. Here's the JavaScript code to draw these two shapes: 

var canvas = document. getElementByld ( 'whiteboard' ) ; 
var context = canvas . getContext (' 2d ') ; 
context . strokeRect (10, 10, 100, 50) ; 
context.fillRect(15,15,90,40) ; 

The strokeRect ( ) method creates a rectangular outline starting at the 
coordinate (10,10) and is 100 x 50 pixels in size. The f illRect ( ) method 
paints a 90 x 40 rectangle starting at coordinate (15,15). Figure 5-4 shows the 
result of the preceding code. 
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Stroking and fitting nonrectanqutar shapes 

To create a shape other than a rectangle, you first need to create a path, a 
sort of connect-the-dots outline of subpaths. After you've defined a path, you 
can then either stroke a line along the path or else fill in the area inside the 
path. 

The following methods of the context object are used for drawing 
nonrectangular shapes: 



beginPath ( ) creates a new path and sets the starting point to the 
coordinate (0,0). 

lineTo (x, y) adds a line segment from the current point to the specified 
coordinate. 

W moveTo (x, y) moves the starting point to a new coordinate that you 
define with the x,y values. 

v 0 closePath ( ) closes an open path and draws a line from the current 
point to the original starting point of the path. 

stroke ( ) draws a line along the current path. 

V f ill ( ) closes the current path and paints the area within it. If you use 
fill ( ) , you don't need to call closePath ( ) because fill ( ) closes 
the path automatically. 
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Here's sample code for a drawing that uses these methods to create two 
adjacent triangles: 



canvas = document . getElementByld ( 
context = canvas . getContext ( ' 2d ' ) , 
// Triangle outline 
context . beginPath ( ) ; 
context .moveTo ( 10 , 10 ) ; 
context . lineTo (10 , 75) ; 
context . 1 ineTo (100,40) ; 
context . lineTo (10 , 10) ; 
context . stroke ( ) ; 
context . closePath ( ) ; 
// Filled triangle 
context . beginPath ( ) ; 
context . moveTo (110, 10) 
context . lineTo (110,75) 
context . 1 ineTo (200,40) 
context . lineTo (110, 10) 
context . fill ( ) ; 



whiteboard ' 



Figure 5-5 shows the incredible work of art that was just created. 
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Working With color and transparency 



ext object has f illStyle and strokeStyle properties that 
bu to define the color, style, and alpha value of your drawing. Table 
5-3 lists all the properties of the context object.) 



Table 5-3 


Available Properties of the context Object 


Property 


Description 


FillStyle 


Provides CSS color or style (gradient. 




pattern) of the fill of a path. 


GlobalAlpha 


Specifies the level of transparency of 




content drawn on the canvas. Floating 




value between 0.0 (fully transparent) and 




1.0 (fully opaque). 



GlobalCompositeOperation Specifies the compositing mode to deter- 
mine how the canvas is displayed relative 
to background content. Values include: 

copy, darker, destination-atop, 
destination- in, destination- 
out, destination-over, lighten, 
source-atop, source-in, 
source-out, source-over, xor. 

LineCap Defines the end style of a line. String 

values include: "butt " forflat edge, 
"round" for rounded edge, "square" 
for square ends. (Defaults to "butt".) 

LineJoin Specifies the way lines are joined 

together. String values include: "round", 
"bevel", "miter". (Defaults to 
"miter".) 

lineWidth Specifies the line width. Floating point 

value greaterthan 0. 

miterLimit Specifies the miter limitfor drawing a 

juncture between line segments. 

shadowBlur Defines the width that a shadow covers. 

shadowColor Provides CSS color for the shadow. 

shadowOf f setx Specifies the horizontal distance of the 

shadow from the source. 

shadowOf f setY Specifies the vertical distance of the 

shadow from the source. 



StrokeStyle 



Defines the CSS color or style (gradient, 
pattern) when stroking paths. 
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ct.fillStyle="#111202" ; 
ft.strokeStyle=rgb(255, 120, 125) 



The alpha value can be assigned to the shape you're filling in using the 
rgba ( ) . For example: 



context. fillStyle = "rgba (13 , 44 , 50 , 0.9)"; 



For example, the following code draws two circles in the canvas. The large 
circle has a 60 percent transparency value, whereas the smaller circle has a 
50 percent transparency value: 

var canvas = document. getElementByld ( 'myCanvas ') ; 
var context = canvas . getContext (' 2d ') ; 
context. fillStyle = " rgba (23 , 44 , 70 , 0.6)"; 
context . beginPath ( ) ; 

context. arc (50, 90, 50, 0, 360, false); 
context . f ill ( ) ; 

context. fillStyle = " rgba ( 0 , 100 , 0 , 0 . 5 ) " ; 
context . beginPath ( ) ; 

context. arc(80, 70, 70,0, 360, false); 
context . f ill ( ) ; 



Figure 5-6 shows the two colored, semitransparent circles. 
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Chapter 6 



nyone Listening? Working 
with Events 



In This Chapter 

Understanding how events work 
Introducing the AIR model 
Preventing default behaviors 
Understanding event flow 



t/My hen you create an AIR application, one of your major objectives is to 
▼ ▼ be able to respond to events that occur from the time your application 
loads to the time it finishes. When the app loads, you will probably have an 
initialization routine. When the user clicks the Save button, perhaps you have 
a saveToFile ( ) function that is called. Or, suppose a user wants to retrieve a 
list of customer records she needs to contact. Your application sends off a data- 
base query and then waits for the database engine to deliver results before pro- 
cessing them. Each of these is an example of an event-driven 
application. 

In this chapter, I show you to how to work with and respond to user and 
system events in Adobe AIR. 



The heart of Adobe AIR event system is a matching pair of events consisting 
of an event and an event listener. To illustrate the nature of this pair, I'll draw 
some parallels with the real world. Suppose you're charged to go to a press 
conference introducing a new soft drink and are responsible for writing an 
article on that beverage for Soda Monthly magazine. You don't think much 
about it, but actually much of what you do to cover that conference is listen 
and wait for something to happen and then respond to those events when 
they transpire. For example: 




Responding to Events 
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When the maker of the soda makes an outrageous claim, you laugh and 
e it down. 



v 0 When two reporters behind you are bickering, you choose not to listen 
to their conversation. 

v 0 When samples of the new carbonated soda called Gel-ola are passed out, 
you eagerly jump in line to get your free drink. 

When you taste the new beverage, you nearly gag as you drink the 
sickeningly sweet, cola-tasting liquid with a semi-solid, gel-like 
substance. 

When the conference ends, you travel back to the office to finish the 
story, armed with a case of Gel-ola to hand out to your coworkers. 



Bringing this back to the world of AIR development, much of the normal 
operation of an AIR app operates in the same event-driven manner. AIR has 
a vast cornucopia of events that you can choose whether to react (or, in 
programming terms, listen) to. For those events that you want to listen to, 
you define functions that are called when the event occurs during the 
execution of the application. A function that responds to an event is called 
an event listener or event handler. 



Event handling in the HTML DOM 

Since the early days of JavaScript, Web pages have had the idea of event 
handlers. In fact, if you've ever worked with client-side JavaScript, you are 
very familiar with event handlers. HTML elements have certain "on" events 
associated with them that you can assign JavaScript functions to. For example, 
the following code uses several "on" events to respond to both browser and 
user events: 

<body onload="init ( ) "></body> 

<input type= " submit " onclick="suhmitForm( ) "></input> 
<img src= "button_on . png " onkeydown= " showlnf o ( ) " / > 

Or, in a normal Web page, you could also use a callback function, such as: 

document . getElementByld ( "btnSubmit "). onclick = submitNow; 

Using this, you tell the submitNow ( ) function to execute when the btnSubmit 
object is clicked. 
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Perhaps most significant, however, the W3C DOM Level 2 event model 
introduced the concept of "event listeners" with the addEventListener ( ) 
Event listeners are arguably the best way to attach an event with its 
Not only can you define a listener all inside of your script, but you 
can also attach multiple event handlers to the same event. 



Here's an example of adding the init ( ) function as a listener to the load 
event of the window object: 

window. addEventListener (" load" , init) ; 

Notice that the function does not have parentheses included when you assign 
it as a handler. 

You can continue to associate events to handlers in any of these three fashions 
for standard DOM object events in HTML applications. 



Registering events in the A\R event model 

The Adobe AIR event model is based on the W3C DOM Level 3 events 
specification. As a result, to "register" an event listener to the event of an 
AIR object, you need to call the associated object's addEventListener ( ) 
method. This method says, in effect: "Hey, Mr. Object, when event X occurs, 
you need to execute function Y." The basic structure looks like this: 

eventTarget . addEventListener ( [air. ] EventClass . EVENT_NAME, 
eventHandler ) ; 

For example, suppose you want to execute a function after an AIR File 
object (with the instance name f s) has opened a local file for reading and 
writing. The associated AIR event is [air . ] Event . complete. Here is the 
code: 

fs . addEventListener (air . Event .COMPLETE, onFileRead) ; 



Working With Etfent Objects 

When the event occurs and triggers the event handler, it dispatches an event 
object to the handler. This object is an instance of the Event class or one of 
its many subclasses, such as HTTPStatusEvent or lOErrorEvent. You will 
often use this object instance to help you process the event successfully. 
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For example, an HTTPService object dispatches a FaultEvent in case 
something goes awry during an HTTP request. The FaultEvent instance 
to its handler as a parameter. The handler can then use the event 
needed. In the case of an error handler like this, you can display the 
message property of the event object (see the bolded call that follows) to let 
the user know what went wrong. Here's the JavaScript code: 



httpService . addEventListener (air . FaultEvent . FAULT , 

onFetchError ) ; 
function onFetchError ( event ) 
{ 

alert ( "The following error occurred when fetching the 
RSS feed: " + event .message) ; 

} 



Here's a second example of using the event object (see bolded code) to 
display details of an error that occurs during a SQL database operation. In 
ActionScript: 



private function onDatabaseError (event : SQLErrorEvent) : 
void 

{ 

Alert . show (event .error .message + " Details: " + event, 
error .details) ; 

> 



But event objects are far more useful than just providing error details. 
Consider the handler of a drag drop event. In the following code, the handler 
uses the event . clipboard. hasFormat ( ) and event . clipboard. get- 
Data ( ) methods of the NativeDragEvent object (see bolded code) to cap- 
ture the data being dropped onto the application: 

public function onDragDrop (event :NativeDragEvent) : void 
{ 

if (event .clipboard. hasFormat (ClipboardFormats . TEXT_FORMAT ) ) { 

var s:String = ( event . clipboard. getData (ClipboardFormats .TEXT_FORMAT, 

ClipboardTransf erMode . ORIGINAL_PREFERRED) as String); 
processDroppedText (s) ; 

} 

} 



When you register an event to be captured, you identify it by its event class 
and its type property (which is expressed as a constant value). For example, 
the NativeDragEvent class has several specific events that you can capture: 



NativeDragEvent . NATIVE_DRAG_COMPLETE 
NativeDragEvent . NATIVE_DRAG_DROP 
NativeDragEvent . NAT I VE_DRAG_ENTER 
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NativeDragEvent . 


.NATIVE, 


_DRAG_ 


_EXIT 


NativeDragEvent . 


.NATIVE, 


_DRAG_ 


_OVER 


"YjcMfc^eDragEvent . 


.NATIVE, 


_DRAG_ 


_START 


/tja\^^DracrEvent . 


.NATIVE, 


_DRAG_ 


_UPDATE 



Therefore, if you wanted to assign a listener to the NativeDragEvent . 
NAT I VE_DRAG_ENTER and NativeDragEvent . NATIVE_DRAG_DR0P events, 
your code would look like this: 

addEventListener (NativeDragEvent .NATIVE_DRAG_ENTER, 
onDragln) ; 

addEventListener (NativeDragEvent . NATIVE_DRAG_DROP , 
onDragDrop) ; 



For the onDragln ( ) and onDragDrop ( ) functions, the NativeDragEvent 
is passed as a parameter. So, in ActionScript, the empty functions are shown 
as follows: 

private function onDragln (event : NativeDragEvent ) : void 

{ 

} 

private function onDragOut (event : NativeDragEvent ) : void 

{ 

} 

Event is the base class of all AIR event objects. However, most AIR objects 
that you work with will have events that are subclasses of the base Event. 
There are far too many to simply list here, so you'll want to check the event 
type for each event you want to listen to in your application. 



Overriding Default Behaviors 

In addition to the handlers that you explicitly define in your source code, you 
should also be aware of default behaviors, or behaviors that automatically are 
performed when an event is triggered. You can prevent most default behaviors 
from occurring by adding preventDef ault ( ) in an error handler. For example, 
the cut, copy, and paste commands automatically send data to or receive it from 
the Clipboard in edit boxes of an AIR application (such as a textarea). To 
prevent this default behavior, you need to define a handler and then add 
preventDef ault ( ) . The handler code might look something like this in 
JavaScript: 
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function onCopy ( event ) 

sel = window. getSelection () ; 

t . clipbardData . setData ( selection + " (Text portions 
copyright © 2009, WackyTacky, Inc. So there.)" 
) ; 

event .preventDefault ( ) ; 

} 



In this sample code, the default onCopy event is intercepted so that a 
copyright notice can be appended to the end of the text selection. 

If you want to test to see whether you can cancel an event using prevent 
Default ( ) , you can check its cancelable property. For example: 



if (event . cancelable) 
{ 

event .preventDefault ( ) ; 

} 

else 
{ 

cry ( ) ; 

} 



Understanding the Flout of Events 

When a nonvisual AIR object, such as HTTPRequest or File, is the target 
of an event, AIR dispatches the event object directly to it. If there is a default 
behavior, that behavior executes. Or, if an event listener is attached, that 
routine is called. 



However, when there is a visual object that is in the Flash/Flex display list 
(the list of visible UI objects) or in the HTML DOM, the flow of events is 
trickier. The reason is that some events can be associated with more than 
one element on-screen. For example, if a user clicks a textarea, the click 
event could potentially be associated with the textarea, its div container, 
or maybe even the document itself. Suppose you have click event handlers 
defined for each of these DOM objects. Which handler is triggered first? 
Given this reality, you should have an understanding of the event flow of an 
AIR app to help you anticipate how your AIR application will respond. The 
following sections show you the event flow in the Flex/Flash display list as 
well as the HTML DOM. 
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In a Flex/Flash application, for example, the stage object is at the top of the 
display list. The rest of the display objects are then structured in a hierarchy 
cfc» U«4 beneath the stage object. When AIR dispatches an event object for 
f!\3^ list event, the event object travels through the display list in three 
distinct phases, as follows: 

Capture phase: During the capture phase, the event object travels from 
the stage object down the node list to the target object. 

W Target phase: During the target phase, the event object is at the target 
object. 

Bubbling phase: In the bubbling phase, the event object travels back up 
through the hierarchy all the way back to the stage. 

The practical implication of this event flow is that you can add event listeners to 
any object within the display list hierarchy rather than just to a single target. 

By default, events are ignored during the capture phase and captured first at 
the target phase followed by the bubbling phase. That's the normal event flow 
and will work for you under most situations. 

However, if you'd prefer to capture during the capture phase, you need to 
add a new parameter to addEventListener ( ) that I have not mentioned 



yet. Specifically, you 


need to include the optional useCapture parameter to 


addEventListener 


( ) and set 


t 


to true: 






var useCapture 


= true; 










eventTarget . addEventListener ( [air 


. ] EventClass . EVENT_NAME , 


eventHandler , 




useCapture) ; 





When useCapture is true, the listener processes the events during the 
capture phase and the events in the target and bubbling phase are ignored. 



If you wanted to listen for an event in all three phases, you would actually 
need to call addEventListener ( ) two times, toggling the value of the 
useCapture parameter. 

Figure 6-1 shows the display list of a Flex application. 



Now suppose the following handlers are defined: 



stage 


addEventListener ( MouseEvent 


CLICK, 




stageClickHandler ) ; 




textl 


addEventListener ( MouseEvent 


CLICK, 




textClickHandler ; 
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Figure 6-1: 

Event flow 
of an AIR 
application. 
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When the user clicks the mx : Text element, AIR runtime sends the event 
object to the stage. However, since useCapture=f alse, its listener is not 
dispatched during the capture phase. Instead, the event object continues 
down the hierarchy to the mx : HDividedBox, to the mx : Box, and finally 
to the target mx: Text. Once here, its event listener is triggered, calling 
textClickHandler ( ) . The event object then bubbles back up through 
the display list hierarchy. When it reaches the stage this time around, the 
stageClickHandler ( ) is called. 
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In This Chapter 

Understanding the kinds of AIR windows 
Creating the initial window of an application 
Setting the style of a window 
Creating a window programmatically 
Creating nonrectangular windows 



■ Mne of the ways in which college students or young adults know that 
\r they're on their own and away from the apron strings of their parents 
is when they get their own digs — their own place to live in and call home. 
Likewise, the primary way in which an AIR-based rich Internet application is 
distinct from a browser-based app is that it has its own on-screen home — a 
window independent from the browser in which it can do its own thing. 

In this chapter, I show you how to create and work with windows as you 
develop your Adobe AIR applications. You discover how to "style" them like 
other native windows. Heck, I even show you how to create nonrectangular 
windows. 

Although it may be more work to deal with native windows than with a 
normal Web application, you'll find your efforts paying off in terms of the 
power and control doing so brings you. 



Exploring AlK Windows 

There are three different categories of native windows that can be part of an 
AIR application. In most cases, the type that you use will often depend on the 
development tool you're working with to create your app. The three categories 
of windows are as follows: 
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W HTML window: An HTML window contains a normal HTML document, 
which displays content using a mixture of HTML, CSS, and JavaScript. It 



eated from the air . HTMLLoader object. 



L windows are a special type of NativeWindow window (see the 
next bullet). You can access the NativeWindow instance of an HTML 
window through its nativeWindow property. 

HTML developers will primarily work with HTML windows, although 
Flex and Flash developers can create HTML windows as well. 

ActionScript NativeWindow: A NativeWindow window contains Flash or 
Flex content and is created programmatically using the NativeWindow 
class. 

Flash developers will typically work with ActionScript windows 
using the Flash stage and display list, although they can be created 
programmatically by Flash, Flex, and HTML developers. 

t<" Flex mx:Window: When working with Flex Builder, you create windows 
typically composed of MXML components that you add inside Flex 
Builder or through ActionScript code. These windows are contained by 

mx : WindowedAppl i cat ion or mx : Window elements. 

As you would expect, the Flex windows are available only for Flex 
developers. 



Creating the Initial WindouJ 

The main window of an application is created by AIR runtime based on the 
property settings inside of the initialWindow element of the application 
descriptor file (typically application. xml). 

Because you can specify the visibility of the initial window, the main window 
can serve as your main application window, or it can remain hidden and be 
used to open other windows. 

There are several required and optional properties that are defined as child 
elements inside of initialWindow. These are listed in Table 7-1. 




Table 7-1 


Initial Window Properties 




Property 


Values Description 


Required 


content 


Filename HTML or SWF filename 


Yes 




containing the main 






content of the app. URL 






is relative to the root 






application folder. 
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Property 


Values 


Description 


Required 




Apptitle 


Title of the main application 
window. (Note: A title 
defined in the content file 
will override this setting.) 


No 


systemChrome 


standard, 
none 


Indicates whetherto use 
the chrome of the native 
OS. (See the "Setting the 


No 






Window Style" section 
below.) 




transparent 


true, 

false 

(default) 


Indicates whether the 
main window supports 
alpha blending. When set 
to true, then system 
Chrome must be none. 
(See the "Setting the 
Window Style" section.) 


No 


visible 


true, 

false 

lrlpfanlt\ 

\ U c 1 CI U 1 1/ 


Specifies whetherto make 
the main window visible 

\A/hpn it InaH*; 

VVIICII 11 IUqUo, 

However, in Flex-based 


No 






apps, this property is 
ignored. Instead, Flex 
apps use the visible 
property in mx: win 

do we dApp 1 i c a t i on 
instead. 




minimizable 


true 
(default), 

false 


Determines whether the 
window can be minimized. 


No 


maximizable 


true 
(default). 


Determines whether the 
window can be maximized. 


No 




false 


(On Mac OS X, both 

maximizable and 
resizable must be 
set to false to prevent 
resizing.) 




resizable 


true 
(default), 

false 


Determines whether the 
window can be resized. 
(On Mac OS X, both 

maximizable and 
resizable must be 
set to false to prevent 
resizing.) 


No 



(continued) 
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W — 


Values 


Description 


Required 


widen 


Integer 


Specifies initial width 
(in pixels) of the main 
window. 


No. If not 
specified, 
then size 


height 


Integer 


Specifies initial height 
(in pixels) of the main 
window. 


and posi- 
tioning 
are deter- 






mined by 
the OS 
(for HTML 


X 


Integer 


Specifies initial x position 
of the main window. 


Y 


Integer 


Specifies initial (/position 
of the main window. 


files) or 
the root 
file (SWF 
files). 


minSize 


width height 
(in pixels) 


Indicates the minimum 
size of the window. 


No 


maxSize 


width height 
(in pixels) 


Indicates the maximum 
size of the window. 


No 



Here's an example of the initialwindow section of the application 
descriptor file, using all the available properties: 

<initialWindow> 

<content> index . html</content> 

<title>My Application</title> 

< sy s t emChrome > s t andar d< / sy s t emChr ome > 

<transparent> f alse< / transparent^ 

<visible>true</visible> 

<minimizable>true< /minimi zable> 

<maximizable>true</maximizable> 

<resizable>true</resizable> 

<width>600</width> 

<height>400</height> 

<x>10</x> 

<y>10</y> 

<minSize>200 200</minSize> 
<maxSize>900 900</maxSize> 
</ initialWindow> 



You can also set some of the properties of the initial window in your code when 
the application loads. If your changes would be noticeable on-screen, you want 
to set the visible property to false (<visible>f alse</visible>). Setting 
this property to false enables the processing to occur without noticeable 
redraws on-screen when the window's position, size, or layout is changing. Then, 
after your changes are made, you can activate the window to make it visible. 
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However, if you're using Flex Builder to create your app, forget the visible 
property in the application descriptor file. It is ignored. Instead, set the 
*ijibtli*ii through the visible property of the mx: WindowedApplication 



In HTML, you add the code in the window's load handler: 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 

Transitional//EN" "http: //www.w3 . org /TR/ xhtml 1/ 
DTD/xhtmll-transitional .dtd"> 

<html xmlns= "http : / /www. w3 . org/ 19 9 9 /xhtml " > 

<head> 

<meta http-equiv=" Content-Type" content= " text/html ; 

charset=utf -8 " /> 
<title>Test</title> 

<script type=" text /javascript" language=" JavaScript" 
src= " assets /AIRAliases . j s "></script> 

<script type=" text /javascript" language=" JavaScript" 
src= " assets /util . j s " ></script> 

<script type=»text/ javascript» language=»JavaScript»> 

window. addEventListener (' load ' , initialize, false); 

function initialize () { 

window. nativeWindow.y =10; 
window. nativeWindow.x = 10; 
window. nativeWindow. activate ( ) ; 

} 

</ script> 
</head> 

<body> 

<div id=" canvas "> 

<hl>Welcome to Adobe AIR.</hl> 

<p>Don ' t go messin' with my Adobe AIR.</p> 

< input id= "btnLaunch" type= " submit " value=" Launch" /> 

</div> 

</body> 

</html> 

For a Flex mx: WindowedApplication, assign a handler to its 
windowComplete event: 

<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 

<mx : WindowedApplication xmlns :mx= "http : / /www. 

adobe . com/2 00 6 /mxml " layout= " absolute " 
title="AIRBaby ! " width="429" height="209" 
windowComplete="initWindow( ) " visible="false"> 

<mx: Style source="def ault . ess " /> 

<mx: Script> 
<! [ CDATA [ 
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private function initWindow( ) : void { 
age . nat iveWindow . maximi ze ( ) ; 
age .nativewindow. visible = true; 

} 



] ]> 

</mx: Script> 

<mx: Label text= " Super ! " x="17" y="19"/> 
</mx: WindowedApplication> 

In this example, the window instance is referenced using stage . 
nativewindow. The maximize ( ) method is then called to maximize the 
window. Finally, the stage. nativewindow. visible property is set to 
true. 



Setting the WindouJ Style 

The initial window and additional windows you create on your own have 
several style options that you can specify at the time you create the window. 
After the window is created, you can't change its properties. You can define a 
window style by its system chrome, transparency, and type. 

System chrome 

Normal windows that you work with have chrome around them. Chrome is a 
techie term that refers to the UI controls of the operating system that are 
outside the content area of a window. So, just as a car might have shiny 
chrome trimming, a bumper, and a grill that cover the vehicle, so the chrome 
of an OS window surrounds and complements the window itself. Examples of 
chrome include the title bar, the Minimize/Maximize/Restore buttons, menu 
bars, and toolbars. 




AIR does not support the following chrome UI elements: Windows title bar 
icon, Mac OS X proxy icon (icon on the toolbar), Mac OS X toolbars, and 
alternate or nonstandard system chrome. 



You can set the chrome of an application by setting the systemChrome 
property of the NativeWindowlnitOptions object and, for initial windows, 
the systemChrome element of the application descriptor file. I discuss 
the NativeWindowlnitOptions object more in the "Creating a Window 
Programmatically" section, later in this chapter, but for now, I show you how 
to assign the systemChrome value from code. In HTML, you write: 
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var options = new air .NativeWindowInitOptions ( ) 



option 

pBooRs 



tions . systemChrome 
Flex/Flash: 



'standard" 



var options : NativeWindowInitOptions = new 

NativeWindowInitOptions ( ) ; 
options . systemChrome = Nat iveWindowSys temChrome . STANDARD; 

There are three types of chrome: 



Standard OS chrome: When you assign standard (HTML) or 
NativeWindowSystemChrome . STANDARD (Flex/Flash) to the system 
Chrome property, the window uses the system chrome of the native OS. 
Figures 7-1 and 7-2 show the standard chrome surrounding the same 
AIR window running under Windows and Mac. Notice that the chrome 
changes based on OS, but the content inside the window remains the 
same. 



Figure 7-1: 

Standard 
chrome 
(Windows). 



Flexible AIR _ 

ate an AIR window automagically' 
systemChrome: standard » . 
transparent: false ▼ 
typ«i a"V w 

Style: Flex ▼ 



ElLaJB 



Launch Window 



Figure 7-2: 

Standard 
chrome 
(Mac). 



« o o 



Create an AIR wintiowautomaglcally! 
system Chrome: standard ▼ 

transparent: false » 

type: any ▼ 

Style: 



Flex 



Launch Window 



V Custom chrome: By assigning none (HTML) and NativeWindow 

SystemChrome .NONE (Flex/Flash) to the systemChrome property, you 
disable the standard chrome of the OS. When you use none with HTML 
or NativeWindow windows, you need to handle user interactions with 
the window, such as window movement. 
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When you're working with transparent or nonrectangular windows, you 
need to use none. 



chrome: When you assign sy st emChrome = NativeWindow 
temChrome . NONE for a Flex mx : Window or mx : Windowed 
Application window, Flex adds its own custom titlebar, Minimize/ 
Maximize/Restore buttons, status bar, and resize gripper. Figure 7-3 
shows the customized Flex chrome running on Windows. 



Figure 7-3: 

Flex style 
chrome 
(Windows). 



exible AIR 

Create an AIR window automagicallyl 
systemChromei none » i 

transparent! true ▼ 

typei 

Style; 



Flex 



Launch Window 




You can get rid of the Flex chrome by setting the window's showFlex 
Chrome property to false. (You can see an example of this in the 
"Creating a Window Programmatically" section, later in the chapter.) Or 
if you want to hide a single chrome element, you can do that by setting 

the showTitleBar, showGripper, or showStatusBar property to 
false. 

Although the Flex chrome appears to surround the window content 
replacing the native OS chrome, the custom chrome is actually drawn 
by Flex inside the window boundaries and is automatically programmed 
to handle user interactions. However, when sizing your window, you'll 
need to account for the extra height that the custom chrome takes up. 

Flex chrome is available only for AIR applications written in Flex Builder 
that use mx : Window or mx: WindowedApplication windows. If you 
create a Flash or HTML-based app and want your own custom chrome, 
you need to create it yourself. 



Transparency 

Adobe AIR supports alpha blending, which is the process of combining a window 
with the desktop or other windows to create partial or full transparency. 

The AIR window and each UI object contained by the window has an assignable 
alpha value from 0 to 1.0 that determines the level of transparency: 1.0 means 
fully opaque, and 0 means fully transparent (elements default to 1.0). Therefore, 
when a window is set to transparent, its background is partially or fully hidden 
(depending on its alpha value), and any window area that does not contain a UI 
element is not visible. 
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To enable this functionality, you need to do the following: 

I^Sat^the transparent property to true at the time the window is created. 

J*\fe«iuse a transparent window can't have system chrome, set the 
systemChrome property to false. 

Because HTML apps display windows with an opaque background even 
when you set transparent property to true, you also need to set the 

air . HTMLLoader . paintDef aultBackground property to false. 

Optionally assign an alpha value to the window. 

You can do this in HTML through the alpha property for a window 
you create with air . HTMLLoader . createRootWindow ( ) . Flex also 
enables you to specify an alpha value through the Property Inspector 
when you're designing an mx : WindowedApplication or mx : Window. 

The following HTML code shows you how to create a transparent window: 

var options = new air .NativeWindowInitOptions () ; 

options . systemChrome = "none"; 

options. transparent = "true"; 

var windowBounds = new air . Rectangle (200 , 250 , 300 , 400 ) ; 

htmlLoader = air . HTMLLoader . createRootWindow ( true , 
options, true, windowBounds); 

htmlLoader . paint sDef aultBackground = false; 

htmlLoader . load (new air. URLReguest ( "win2 .html" ) ) ; 

I cover the createRootWindow method in the upcoming section "Creating 
a Window Programatically," so don't concern yourself with the particulars of 
window creation for now. Instead, notice how the three bolded property assign- 
ments in the preceding code are used to create a transparent HTML window. 

For Flex/Flash, use the following code to set up the initialization options for a 
window you will be creating: 

var options : NativeWindowInitOptions = new 
NativeWindowInitOptions ( ) ; 

options . systemChrome = NativeWindowSystemChrome . NONE ; 
options . transparent = true; 

Figure 7-4 displays a transparent window with Flex chrome. As you can see, 
the desktop wallpaper partially shows through the semitransparent window 
(set at 0.5). Figure 7-5 shows a fully transparent window, with just its controls 
showing up. 



DropBoo 
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Figure 7-5: 

Chromeless, 
transparent 
window 
with desk- 
top showing 
through 
(Mac). 



This is an fcxtraordM arv seaonti vnnaow 

3 




Window type 

You can use the type property of an AIR window as a shortcut to define both 
the chrome and visibility attributes of a window you create programmatically. 
There are three types of AIR windows that you can define using the type 
property: 

V Normal is a standard OS window. The initial window of an AIR application 
is always defined as a normal window. See Figures 7-1 and 7-2. 

r* Utility is a palette style window. See Figures 7-6 and 7-7. 

W Lightweight is designed for notification type windows. 



Flex Style 



Figure 7-6: 

Utility 
window 
(Windows). 



1 extraordinary sei 
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pta)ks 



Utility 
window 
(Mac). 



ft n O You've Been Chromed 



i extraordinary second window 



The type property is not available for the initial window of an application. 

Table 7-2 shows the support of OS chrome and other UI features based on the 
window type. 



Table 7-2 






AIR Window Types 






Type 


Descrip- 


Chrome 


Win- 


Win- 


Mac 


Initial 


system 




tion 




dows 


dows 


OSX 


win- 


Chrome 








Task 


System 


Win- 


dow 


value 








Bar 


Menu 


dow 


















Menu 






Normal 


Normal 


Full 


Yes 


Yes 


Yes 


Yes 


standard 




window 
















Utility 


Palette 


Slim 


N 


0 


Yes 


No 


No 


standard 




window 
















light 


"Light- 


None 


N 


0 


No 


No 


No 


none 



weight 



weight" 
notifica- 
tionstyle 
widows 



To create a utility window in HTML, you use the following windows initializa- 
tion options: 

var options = new air .NativeWindowInitOptions ( ) ; 
options . systemChrome = "standards- 
options . transparent = false; 
options. type = "utility"; 
Or, to set the initialization settings for a lightweight window in Flex/Flash: 



Part II: AIR Application Design 



d Books 

option 



options :NativeWindowInitOptions = new 
NativeWindowInitOptions ( ) ; 
s . systemChrome = NativeWindowSystemChrome . NONE ; 
s . transparent = false; 
options. type = NativeWindowType . LIGHTWEIGHT; 



Table 7-3 shows all the window initialization properties that you can work 
with. 



Table 7-3 Window Initialization Properties 



Property 


Values 


Default value 


Valid for initial 
window 


systemChrome 


standard, 
none 


standard 


Yes 




Type 


normal, 

utility, 

lightweight 


normal 


No (initial window 
is always normal) 


Transparent 


true, false 


false 


Yes 




Maximizable 


true, false 


true 






Minimizable 


true, false 


true 






Resizable 


true, false 


true 







Creating a Windort Programmatically 

Although the initial window is created automatically by AIR on app launch, 
additional windows must be explicitly created programmatically. The follow- 
ing sections show you how to create HTML windows, mx: windows (Flex), 
and NativeWindows (Flash, Flex, or HTML). 



Creating an HTML utindow) 

In a typical HTML-based AIR application, when you're working with addi- 
tional windows, you want to display sandboxed HTML content inside the new 
window. To do so, you want to do four tasks: 

W Set the basic window style properties through air . 

NativeWindowInitOptions ( ) . 

Set the dimensions and position of the window using an air . 

Rectangle ( ) instance. 
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v 0 Create the window using the air . HTMLLoader . createRootWindow ( ) 
method, passing along the info specified by the first two tasks. 



the HTML page using the window's load ( ) method. 



Using this four-step process, here's how you can create a utility window to 
display an HTML named win2 . html: 



function launch(){ 



var options = new air .NativeWindowInitOptions () ; 
options . systemChrome = "standards- 
options . transparent = false; 
options. type = "utility"; 

var windowBounds = new air . Rectangle ( 100 , 100 , 300 , 200 ) ; 

newWindow = air . HTMLLoader . createRootWindow (true, 

options, true, windowBounds); 
newWindow. load (new air . URLRequest ( " . . /win2 .html " ) ) ; 

} 



Figure 7-8 shows the window that is created. 



O r> o 

Welcome to Adobe AIR. 

As I Slid before Don't go messin' with my Adobe 

Figure 7-8: *■»'""" ■ 
Utility win- {°EE) 
dow shown 
on a Mac. 



The following code is used to create a chrome-less, transparent window with 
an alpha value of 0.7. Note the property assignments in bold: 



function launch () { 



var options = new air . NativeWindowInitOptions () ; 
options . systemChrome = "none"; 
options. transparent = true; 

var windowBounds = new air . Rectangle ( 100 , 100 , 300 , 200 ) ; 

newWindow = air . HTMLLoader . createRootWindow (true, 

options, true, windowBounds); 
newWindow . alpha = 0.7; 

newWindow. paintsDef aultBackground = false; 

newWindow . load (new air . URLRequest ( " . . /win2 . html " ) ) ; 

} 
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The windows that you create with createRootwindow ( ) are independent of 
the opening window. 



displays the same win2 . html content, but in a different style of 
window container. 



Figure 7-9: 

"ransparent 
window 
with 
desktop 
windows 
showing 
through. 



Welcome to Adobe AIR. 




As 1 said before. Don't go messin' with my Adobe 





If you're trying to display nonsandboxed content in a window you're creating, 
use the JavaScript window . open ( ) method. For example, the following code 
creates a new window: 

newWindow = window. open ( 'http://www.dunimies.com/air/ 
getsupport .php ' , 'Get Application Support', 
'width=400,height=303 ' ); 

Note that this nonsandboxed window would not have access to the AIR API. 



Creating a Flex mxiWindou) 

When working with Flex Builder, you typically create your application 
windows as separate MXML files, each of which uses mx: window as the root 
tag of the document. 

Listing 7-1 lists the contents of the MXML file for this example. 



Listing 7-1: SecondWindow.mxml 

<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 

<mx : Window xmlns : mx= "http : / /www. adobe . com/2 006 /mxml " 
layout=" absolute" width="3 00" height="2 00" 
styleName= " sanschrome " > 

<mx : Style> 

.sanschrome { showFlexChrome : false; background-color:"";} 
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</mx: Style> 

Sript> 
DATA [ 

private function closeWindow ( ) : void { 
this . close ( ) ; 
} 

] ]> 

</mx : Script> 



<mx:Button x="217" y="151" label= "Close " 

click= " closeWindow ( ) "/> 
<mx:Text x="39" y="49" text="This is an extraordinary 

second window
 
 " color= " #000000 " /> 
< /mx : Window> 



Note that the mx : window element is assigned the sanschrome CSS style. 
This style hides the default Flex chrome and any background color. 

When you want to open a chrome-less, transparent instance of this window 
in your app, you simply call the following routine: 

public function openWindow( ) :void { 
secWindow = new SecondWindow () ; 

secWindow. systemChrome = NativeWindowSystemChrome .NONE; 
secWindow. transparent = true; 
secWindow. open ( ) ; 

} 

In this example, I create an instance of the mx : window contained in 
SecondWindow. mxml called secWindow. SecondWindow ( ) is the name of 
the subclass of the Window class. Its name is taken from the MXML filename. 
After you set the basic property settings of the window, you use open ( ) to 
display it. 



Creating an ActionScript NatiVeWindou) 

The third kind of window you can create is a NativeWindow through 
ActionScript. When creating an HTML or mx : window window, you typically 
already have content defined by the HTML or MXML file that you reference. 
However, a NativeWindow does not have an associated content file, mean- 
ing that you need to programmatically add the content yourself at the time 
the window is created. 



DropBook 
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The following example creates a NativeWindow window: 

ic function createWindow ( ) :void { 



} 



Set mxt options 
var options :NativeWindowInitOptions = new 

NativeWindowInitOptions ( ) ; 
options . systemChrome = NativeWindowSystemChrome . 

STANDARD ; 
options . transparent = false ; 
options . type = NativeWindowType . NORMAL ; 

// Create new NativeWindow 

var newWindow: NativeWindow = new 

NativeWindow (options) ; 
newWindow. title = "You've Gone Native"; 
newWindow. width = 500; 
newWindow . height = 400; 

// Create HTML container 

var html Viewer : HTMLLoader = new HTMLLoader () ; 
htmlvi ewer .width = 490; 
htmlvi ewer . height = 3 90; 

// Add to stage 

newWindow. stage . align = StageAlign.TOP_LEFT; 
newWindow. stage . scaleMode = StageScaleMode .NO_SCALE; 
newWindow. stage . addChild ( html Viewer ); 

// Load URL 

htmlvi ewer . load ( new URLRequest ( "http :/ /www. dummies . 
com" ) ) ; 

// Make visible 
newWindow. activate ( ) ; 



The ActionScript routine begins by setting the initialization options. It then 
creates a NativeWindow instance called newWindow and assigns basic size 
properties. An HTML viewer is created to be displayed as content inside the 
window, which is added to the newWindow stage through the addChild ( ) 
method. The window is activated and made visible through the activate ( ) 
method. 



Listing 7-2 lists the source code for FlexAir .mxml. (See Figure 7-1 for a view 
of the window during runtime.) It's an example of creating a window based 
on the input of the user. 
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Listing 7-2: FlexAir.mxml 

version= " 1 . 0 " encoding= "utf -8 " ?> 
ndowedApplication xmlns :mx="http : //www. 

adobe . com/ 2 00 6 /mxml " layout= " absolute " 
title="Flexible AIR" width="429" height="209"> 
<mx: Style source= "default . ess " /> 

<mx: Script> 
<! [ CDATA [ 

import mx . controls . Label ; 

import mx. controls . Text; 

import mx. collections .ArrayCollection; 

import mx.controls.HTML; 

private var secWindow: SecondWindow; 
[Bindable] 

public var chromeOptions : ArrayCol lection = new 
ArrayCollection ( 
[ {label :»standard», data:NativeWindowSystemChrome. 
STANDARD} , 

{label :»none», data:NativeWindowSystemChrome.NONE} 

] ) ; 

[Bindable] 

public var transparentOptions : ArrayCollection = new 
ArrayCollection ( 
[ {label :»false», data: false}, 
{ label : »true» , data: true} 
] ) ; 

[Bindable] 

public var typeOptions : ArrayCollection = new 
ArrayCollection ( 
[ {label :»any», data: null}, 

{label :»normal», data : NativeWindowType . NORMAL} , 
{label :»utility», data: NativeWindowType. UTILITY} , 
{label : »lightweight», data: NativeWindowType. 
LIGHTWEIGHT} 

] ) ; 
[Bindable] 

public var flexOptions : ArrayCollection = new 
ArrayCollection ( 
[ { label : »Flex» , data: true}, 

{label : »NativeWindow», data: false} 
] ) ; 
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ic function createWindow ( ) : void { 



// Set init options 
var options :NativeWindowInitOptions = new 

NativeWindowInitOptions ( ) ; 
options . systemChrome = cbSystemChrome . selectedltem. 
data; 

options . transparent = cbTransparent . selectedltem. data; 
if ( cbType . selectedltem. data != null ) 
options. type = cbType . selectedltem. data; 

// Create new NativeWindow 

var newWindow : NativeWindow = new 

NativeWindow (options ) ; 
newWindow. title = «You ' ve Gone Native»; 
newWindow. width = 500; 
newWindow. height = 400; 

// Create HTML container 

var html Viewer : HTMLLoader = new HTMLLoader () ; 
htmlvi ewer .width = 490; 
html Viewer . height = 3 90; 

// Add to stage 

newWindow. stage . align = StageAlign . TOP_LEFT ; 
newWindow. stage . scaleMode = StageScaleMode .NO_SCALE; 
newWindow. stage . addChild ( html Viewer ) ; 

// Load URL 

htmlvi ewer . load ( new URLRequest («http: //www. dummies . 
com») ) ; 

// Make visible 
newWindow. activate ( ) ; 



public function launchWindow ( ) :void { 

// Flex style window or native? 
if ( ! cbFlexStyle . selectedltem. data ) { 
createWindow ( ) ; 

} 

else { 

// Create window and assign title 
secWindow = new SecondWindow ( ) ; 
// Assign chrome value 

secWindow. systemChrome = cbSystemChrome. 

selectedltem. data; 
// Assign transparent 
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secWindow. transparent = cbTransparent . selectedltem. 
data; 

// Assign window type 

if ( cbType . selectedltem. data != null ) 

secWindow. type = cbType . selectedltem. data; 
/ / Open window 

if ( ( secWindow. systemChrome == 

NativeWindowSystemChrome . NONE ) && 
( secWindow. transparent == true ) ) { 
secWindow. title = «You ' re Flexible»; 

} 

else { 

secWindow. title = «You ' ve Been Chromed»; 

} 

secWindow. open ( ) ; 

} 

} 

] ]> 

</mx: Script> 
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<mx: Label text=»Create an AIR window automagically ! » 

x=»17» y=»19»/> 
<mx:Button x=»289.75» y=»140» label=»Launch Window» 

click=»launchWindow ( ) »/> 
<mx:ComboBox x=»127.75» y=»49» id=»cbSystemChrome» 

dataProvider=» { chromeOpt ions } » width=»l 0 0» / > 
<mx:ComboBox x=»127.75» y=»79» id=»cbTransparent» dataProv 

ider=»{ transparentOptions}» width=»100»/> 
<mx:ComboBox x=»127.75» y=»110» id=»cbType» 

dataProvider=» { typeOptions } » width=»10 0»/ > 
<mx:ComboBox x=»127.75» y=»140» id=»cbFlexStyle» 

dataProvider=»{ f lexOptions}» width=»100»/> 

<mx:Label x=»25.75» y=»51» text=»systemChrome : »/> 
<mx: Label x="25.75" y="81" text= " transparent :" /> 
<mx:Label x=»25.75» y=»112» text=»type : »/> 

<mx:Text x=»25.75» y=»142» text=»Style : 
 » width=»74»/> 
</mx : WindowedApplication> 



In this example, the user specifies the window properties through the 
mx : ComboBox controls and then clicks the Launch Window button. The 
Launch Window button calls the launchwindow ( ) function, which first 
determines whether the type of window should be NativeWindow or Flex. 
If NativeWindow, then the createwindow ( ) function is called. Otherwise, 
the launchwindow ( ) creates an instance of the Secondwindow window 
(Sec ondWindow . mxml) . 
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vantage of windows transparency, you can create nonrectangular 
windows for your AIR apps. Although you can use ActionScript advanced 
drawing techniques to draw nonrectangular shapes, the most straightforward 
way to achieve a common nonrectangular window is to combine transparency 
with an image background. 

Because nonrectangular windows have no chrome, you need to code basic 
window functionality, such as Move, Close, and Minimize. 



Nonrectanqutar Windows in HTML 

To create a nonrectangular window in an HTML application, begin by defin- 
ing a basic HTML file that includes a div element to contain any content. 
Also included here is the reference to include the AiRAliases . j s file: 

<html> 
<head> 

<title>CirculAIR</title> 

<script type=" text /javascript" src= "AiRAliases . j s " ></ 
script> 

</head> 
<body> 

<div id=" canvas "> 

</div> 

</body> 

</html> 



Next, assign a background image to the body. The following example uses a 
circular image named badge . png. The example also adds a basic style for 
the canvas div: 



<style media= " all " > 

body { background : url (' badge .png ' ) no-repeat 0 0; } 
icanvas { text-align: center; } 
</style> 



You can add any content to the HTML file. In this example, some basic text 
and two images are added, which are being used for Minimize and Close but- 
tons inside the div container: 



<img id= "btnMinimize " src= "minimize. png" 

one lick= "minimi zeWindow ( ) "/> 
<img id="btnClose" src=" close. png" 

onclick="closeWindow( ) "/> 
<p class= " circleCaption" >This may be a lame app, but what 

do you expect? <br/xbr/>It 1 s a circle !</p> 
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As you can see, this code assigns onclick event handlers to the two image 
buttons. The minimi zeWindow ( ) and closeWindow ( ) functions are 



Add styles as needed for the page elements. Here's the code: 

#btnMinimize { 

position: absolute; 
top: 55px; 
left: 220px; 



circleCaption { 
margin: 150px 50px 3 0px 50px; 
color: #ffffff; 

font-family: 'Lucida Grande', Verdana, Geneva, Sans- 
Serif ; 
font-size: 17px; 



To give basic functionality to the app, you define handlers for the two image 
buttons: 

function closeWindow ( ) { 

air .NativeApplication.nativeApplication. exit ( ) ; 

} 

function minimi z eWindow ( ) { 

window . nativeWindow. minimize ( ) ; 

} 

Because the window has no chrome, you need to add window move function- 
ality. (If you don't, the user won't be able to move the AIR app around the 
screen.) The handiest way is to trap for the onmousedown event, which you 
can do when the page is loaded, like so: 

function initialize ( ) { 

document .body . onmousedown = function (e) { 
window. nativeWindow. startMove ( ) ; 

}; 

} 

window. addEventListener (' load ' , initialize, false); 




} 



#btnClose { 



position: absolute; 
top: 55px; 
left: 235px; 



} 



Before building the app, you need to make sure that the application descriptor 
file contains the appropriate settings for the initialwindow tag: 



Part II: AIR Application Design 



dBooJ^I 



<initialWindow> 

<content>index . html</content> 
y s t emChr ome >none< / sy s t emChrorae > 
ransparent>true</ transparent> 
ialWindow> 



Figure 7-10 displays the AIR app when it is run. 



i 



A 



This may be a lame app, but 
what do you expect? 



It's a circle! 



Figure 7-10: 

Non- 
rectangular 
AIR app. 





Listing 7-3 shows the HTML source file. 
Listing 7-3: index.html 



<html> 
<head> 

<title>CirculAIR</title> 
<style media="all"> 

body { 

background : url ( 'badge. png' ) no-repeat 0 0; 



ttcanvas { 

text-align: center; 

} 

#btnMinimize { 

position: absolute; 
top: 55px; 
left: 220px; 

} 
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#btnClose { 

sition: absolute; 
ft: 235px; 

}"" 



. circleCaption { 

margin: 150px 50px 3 0px 50px; 
color: #ffffff; 

font -family: 'Lucida Grande', Verdana, Geneva, Sans- 
Serif ; 
font-size: 17px; 

} 



</style> 

<script type=" text /javascript" src= "AIRAliases . j s " ></ 
script> 

<script type= " text/ j avascript " > 

function initialize ( ) { 

/ /window . nativeWindow. addEventListener ( air . Event . 
CLOSING, closeWindow) ; 

document .body . onmousedown = f unction (e) { 
window. nativeWindow. startMove ( ) ; 

}; 

} 

function closeWindow ( ) { 

air .NativeApplication.nativeApplication. exit ( ) ; 

} 

function minimizeWindow ( ) { 

window . nativeWindow. minimize ( ) ; 

} 



window. addEventListener (' load ' , initialize, false); 

</script> 

</head> 
<body> 

<div id=" canvas "> 

<img id= "btnMinimize " src= "minimize. png" 
onclick= "minimizeWindow ( ) "/> 



(continued) 
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id="btnClose" src= "close .png" 

onclick="closeWindow( ) "/> 
" circleCaption" >This may be a lame app, but what 
do you expect? <br/xbr/>It ' s a circle !</p> 



</div> 

</body> 

</html> 



Nonrectanqutar Windows in Flex 

A background image can also be used with mx : windowedApplication and 
mx: window elements in Flex Builder to create nonrectangular windows. The 
first step is to create an mx: WindowedApplication and set its showFlex 
Chrome property to false and be sure that no background is set: 

<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 

<mx : WindowedApplication xmlns :mx= "http : / /www. adobe . 

com/2 006 /mxml " layout=" absolute" height="378" 
width= "356" 
styleName= " sansChrome " > 
<mx: Style> 

.sansChrome { showFlexChrome : false; background- 
color : " " ; } 
</mx : Style> 

</mx : WindowedApplication> 

Next, you can use an mx : image element to display the background image: 

<mx: Image id="imgCircle" x="0" y="0" source= "badge . png " 
width="354" height= " 376 " /> 



Now you add desired content to the mx : WindowedApplication. In this 
example, I add basic text and two mx : image elements for the Minimize and 
Close buttons. (Y ou can use mx : Button elements instead.) Here's the code: 

<mx:Text id= " txtLabel " x="81" y="126" text="This 

may be a lame app, but what do you expect? 


It's a circle!" width="192" 
height="131" color="#FFFFFF" f ontSize= " 17 " 
textAlign= " center " enabled= " true " 
selectable= " false " useHandCursor= " true" /> 

<mx: Image x="211" y="54" source= "minimize . png " 

click= " minimi zeWindow ( ) " id= " ibtnMinimize" /> 

<mx:Image x="226" y="54" source= " close . png" 

click= " closeWindow ( ) " id="ibtnClose" /> 
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As you can see, I add click event handlers to the images. You can define 
these in an mx : Script, as follows: 

DrooBooks-ipt 

<T[CDATA[ 

public function closeWindow( ) :void { 
this . close ( ) ; 

} 

private function minimi z eWindow ( ) :void { 
stage . nativeWindow . minimize ( ) ; 

} 

] ]> 

</mx: Script> 

To add window movement functionality, mouse down events need to be cap- 
tured for the image and text elements. These are defined in an initialization 
routine to be triggered when the application is loaded adding application 
Complete= " initwindow ( ) " in the mx : WindowedApplication. Here's the 
attached function: 



private function initwindow (): void { 




this . imgCircle . addEventListener (MouseEvent . 


MOUSE_DOWN, onMouseDown) ; 




this . txtLabel . addEventListener (MouseEvent 




MOUSE DOWN, onMouseDown) ; 




} 







One final effect that you can add using ActionScript is a drop shadow for the 
image (named imgCircle) using a DropShadowFilter. To do so, declare a 
shadowFilter variable: 



public var shadowFilter : DropShadowFilter; 

Then add the following to initwindow ( ) : 

shadowFilter = new DropShadowFilter () ; 
shadowFilter .color = 0x000000; 
shadowFilter . alpha = 0.5; 
shadowFilter . blurX = 5; 
shadowFilter . blurY = 5; 
shadowFilter . distance = 3; 
addShadow ( this . imgCircle) ; 

Finally, add the addShadow ( ) function, which is referenced in the preceding 
code. This adds the shadowFilter to the image: 
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public function addShadow(comp:DisplayObject) :void { 
comp . filters = [this . shadowFilter] ; 



Before building the app, you need to make sure the application descriptor file 
contains the appropriate settings for the initialwindow tag: 

<initialWindow> 

<content>index . html</content> 

<systemChrome>none</systemChrome> 

<transparent>true</ transparent> 
</ initialWindow> 

Figure 7-11 displays the running nonrectangular AIR app. 



Figure 7-11: 

Non- 
rectangular 
AIR app 
written in 
Flex Builder. 




Listing 7-4 shows the main MXML source file for the application. 



Listing 7-4: CirculAIR.mxml 

<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 

<mx : WindowedApplication xmlns :mx= "http : / /www. adobe . 

com/2 006 /mxml" layout= " absolute " height="378" 

width= "356" 

styleName="sansChrome" applicationComplete= " initWindow ( ) 
" > 

<mx: Style> 

. sansChrome { showFlexChrome : false; background- 
color : " " ; } 
</mx : Style> 



Chapter 7: Windows: Creating Native Application Shells 



public var shadowFilter : DropShadowFilter ; 

private function initWindow ( ) :void { 

this . imgCircle . addEventListener (MouseEvent . 

MOUSE_DOWN, onMouseDown) ; 
this . txtLabel . addEventListener (MouseEvent . 

MOUSE_DOWN, onMouseDown) ; 

shadowFilter = new DropShadowFilter () ; 
shadowFilter .color = 0x000000; 
shadowFilter . alpha = 0.5; 
shadowFilter .blurX = 5; 
shadowFilter . blurY = 5; 
shadowFilter . distance = 3; 
addShadow ( this . imgCircle) ; 



public function closeWindow( ) :void { 
this . close ( ) ; 

} 

private function onMouseDown (evt : MouseEvent ): void { 
stage .nativeWindow. startMove ( ) ; 

} 

private function minimi z eWindow ( ) :void { 
stage .nativeWindow. minimize ( ) ; 

} 

public function addShadow ( comp : DisplayObj ect ): void { 
comp. filters = [ this . shadowFilter ] ; 

} 



] ]> 

</mx: Script> 



<mx:Image id= " imgCircle " x= " 0 " y= " 0 " source= "badge . 
png" width="3 54" height="37 6" 
doubleClick="closeWindow( ) "/> 




<mx : Script> 



} 



(continued) 
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:Text id= " txtLabel " x="81" y="126" text="This 

may be a lame app, but what do you expect? 


It's a circle!" width="192" 
height="131" color= " #FFFFFF " f ontSize= " 17 " 
textAlign= " center " enabled= " true " 
selectable= " false" useHandCursor= " true" /> 
<mx: Image x="211" y="54" source= "minimize . png" 

click= " minimi zeWindow ( ) " id= " ibtnMinimize" /> 
<mx: Image x="226" y="54" source= " close . png" 

click= " closeWindow ( ) " id="ibtnClose" /> 



</mx : WindowedApplication> 
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In This Chapter 

Understanding the types of native menus 
Creating a menu 
Working with menu items 
Processing menu events 

Enabling your app for the Windows system tray and Mac OS X Dock 

•••••••••••••••••••••••••••••••••••••a 



indlessly going along with the crowd may be a bad thing in the real 
world, but I strongly recommend that you go along with the "in" 
crowd when it comes to creating applications. The cool kids, in this case, 
are apps that conform to the basic UI standards and core functionality of 
the native OS. UI conventions help ensure that users instantly know how to 
interact with your app, where to go to find it, and how to get it to perform an 
action. 

With that in mind, Adobe AIR enables developers to build apps that 
conform to the user interface conventions and functionality of the native 
OS. In addition to windows (discussed in Chapter 7), an AIR application also 
interacts with other key parts of a native OS user interface, including the 
menu system, taskbar (Windows), and Dock (Mac OS X). In this chapter, you 
discover how to add these capabilities to your AIR app. 



Exploring the Types of Native Menus 

For Web applications, menus are typically used as a way to navigate to different 
pages of the application. However, these menus are implemented inside a page 
as an on-screen control — not that much different from a button or text field. 
Native OS menus, however, are foreign territory for Web apps; these menus are 
stuff the browser deals with. But Adobe AIR empowers you to use menus as a 
primary way in which a user interacts with your native application. 
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There are several types of menus that you can implement, depending on the 
needs of your app. Table 8-1 lists each of the menu types and indicates the 
for which they are applicable. Also note the Default column in the 
obe AIR automatically adds a default application menu, as well as 
some context (right-click) menus, to your app when running under Mac OS X. 
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Creating a Menu 

Adobe AIR menus are created using the NativeMenu and NativeMenultem 
classes. These menus and menu items that you create in code are distinct 
and independent from the various application, window, and context menus 
that appear on-screen. You can therefore designate a NativeMenu object to 
serve as any of these types of menus. 

Keep in mind the following basic rules of thumb to consider when you create 
AIR menus: 

You have a hierarchy of menu objects. When you create a menu, you 
are creating a hierarchy. A NativeMenu object, which is always at the 
top level of the hierarchy, contains one or more NativeMenultem 
objects. 

V NativeMenultem objects are flexible. A NativeMenultem can represent 
one of three things: a command item, a separator, or a submenu. 
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W The root menu is boss. The NativeMenu instance you designate to 
serve as the application and/or window menu is often called the root 



u or top-level menu. Its NativeMenultem children are displayed 
zontally to form a Menu bar. 



v 0 Submenus are implemented through two objects. A submenu is just 
another NativeMenu instance. However, it is always contained by a 
NativeMenultem and is never directly added to a NativeMenu. Given 
those facts, you can think of a submenu as consisting of two components: 

• A NativeMenultem instance that serves as the container of the 
submenu and displays a menu label for the submenu. 

• The actual menu, a NativeMenu instance that is assigned to the 
submenu property of a NativeMenultem instance. 

Because a submenu is a NativeMenu instance contained by a 
NativeMenultem, be wise in your variable naming, or your code can 
become confusing to read and work with. For example, if you assign 
f ileMenu as the NativeMenultem instance that contains the File 
submenu, you can be confused as to whether you're working with the 
container item or the actual submenu. 

Two names for right-click menus. Adobe AIR features both context 
menus and pop-up menus. However, these two menus are essentially 
the same thing — namely, a menu displayed in place when the mouse is 
right-clicked. The only difference is in usage; context menus have menu 
items specific to a particular on-screen object, whereas a pop-up menu 
is more general purpose in nature. 

Root menus and context menus have structural differences. The menu 
item children of a root menu should be submenus, not commands or 
separators. However, context and pop-up menus often have commands 
and separators in the highest level of their menu structure. 

Menus trigger two events. NativeMenu and NativeMenultem objects 
dispatch displaying and select events: 

• The displaying event is triggered just before the menu or menu 
item is displayed. 

• The select event is triggered when a NativeMenultem com- 
mand item is selected by the user. (Separators and submenus 
don't trigger a select event.) 



Creating a root menu 

To create an application (Mac OS X) and window (Windows) menu for your 
application, you create a NativeMenu instance that will serve as your root 
menu. You can assign this same NativeMenu object to serve as both the 
application and window menu. 
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In JavaScript, you create the top-level NativeMenu instance using air . 

NativeMenu ( ) : 

otMenu = new air .NativeMenu () ; 
In ActionScript, use the following: 

var rootMenu : NativeMenu = new NativeMenu () ; 



Creating submenus 

A root NativeMenu isn't much good on its own, however. Instead, it needs a 
set of NativeMenuitem objects to serve as submenus. To do so, create the 
NativeMenultem and then assign a new NativeMenu instance to its 
submenu property. You then add new items to the submenu. 

Here's the code in JavaScript: 

var f ileMenuItem = rootMenu. addltem( "File" ) ; 

var fileSubmenu = new air. NativeMenu ( ) ; 

f ileMenuItem. submenu = fileSubmenu; 

var newFileltem = fileSubmenu . addltem ( "New" ) ; 

A NativeMenultem is added to the rootMenu instance using air . 
NativeMenuitem ( ) . As you can see from the preceding code, the 
addltem ( ) creates a new menu item with the menu label specified in the 
parameter. 

Using ActionScript, you write the following: 

var f ileMenuItem : NativeMenultem = rootMenu. 
addltem ( "File" ) ; 

var fileSubmenu : NativeMenu = new NativeMenu () ; 
f ileMenuItem . submenu = fileSubmenu; 
var newFileItem:NativeMenuItem = fileSubmenu. 
addltem( "New" ) ; 



You could also use the addSubmenu ( ) method as a shortcut to eliminate one 
line of code. It enables you to assign a NativeMenu instance as a submenu at 
the same time that you create the menu item. In JavaScript: 



var fileSubmenu = 


new air . NativeMenu ( ) ; 


var fileMenuItem 


= rootMenu . addSubmenu ( fileSubmenu, 


"File" ; 


) ; 



DropBooks 
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Using this shortcut, you can go one step further and create separate routines 
for creating each submenu. The following example creates a root menu and 
s four submenus to it, each of which is created in a helper function: 



rootMenu = new air .NativeMenu () ; 
var f ileMenuItem = rootMenu . addSubmenu (createFileMenu (), "File" ) 
var editMenuItem = rootMenu. addSubmenu (createEditMenu (), "Edit" ) 
var viewMenuItem = rootMenu . addSubmenu (createViewMenu (), "View" ) 
var helpMenuItem = rootMenu . addSubmenu (createHelpMenu (), "Help" ) 



The following syntax is also valid, although you would not be able to refer- 
ence by name the NativeMenu It em children of rootMenu: 



var rootMenu = new air .NativeMenu () ; 
rootMenu . addSubmenu (createFileMenu ( ) , "File") ; 
rootMenu . addSubmenu (createEditMenu ( ) , "Edit") ; 
rootMenu . addSubmenu (createViewMenu ( ) , "View" ) ; 
rootMenu . addSubmenu (createHelpMenu ( ) , "Help" ) ; 



Creating menu commands 

A menu command is created using the NativeMenu addltem ( ) method 
and then adding an event listener that triggers a function when the item is 



selected. Consider the following 


J 


avaScript: 




var fileSubmenu = new air. NativeMenu ( ) ; 

var newFileltem = fileSubmenu . addltem (new air. 
NativeMenuItem ( "New" ) ) ; 





newFileltem. addEventListener ( air . Event . SELECT, fileNew); 



function fileNew () { 

alert ("You created a new document. You must be proud!"); 

} 

newFileltem is added as a new NativeMenuItem under fileSubmenu 
and given the label of New. A select event listener is added to execute the 
fileNewO function. 

Consider a slightly more complete ActionScript example. Pay special atten- 
tion to the bolded lines, which create a menu item and attach a select event 
handler to it: 
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private function initWindow( ) :void { 

var rootMenu : NativeMenu = new NativeMenu () ; 

f ileSubmenu : NativeMenu = new NativeMenu () ; 



var f ileMenuItem : NativeMenuItem = rootMenu . addl tern (new 

NativeMenuItem ( "File" ) ) ; 
f ileMenuItem . submenu = f ileSubmenu; 



var newFileItem:NativeMenuItem = f ileSubmenu. addltem(new 

NativeMenuItem ( "New" ) ) ; 
newFileltem.addEventListener ( Event . SELECT, f ileNew) ; 



} 



public function fileNew(evt: Event) : void { 

mx. controls. Alert. show ( "You created a new document, 
must be proud ! " ) ; 

} 



YOU 



Notice that the event handler function needs to pass the Event instance as a 
parameter even if you don't plan on using it. 



Creating menu separators 

A menu separator is a horizontal line that does what its name implies — sep- 
arates items in your menu into logical groupings. To create a menu separator, 
you set to true an optional isSeparator parameter in the NativeMenuItem 
constructor. 

The following JavaScript code adds separators between the New, Save, and 
Exit menu items: 

var f ileSubmenu = new air. NativeMenu ( ) ; 

var newFileltem = f ileSubmenu . addltem (new air. 

NativeMenuItem ( "New" ) ) ; 
newFileltem. addEventListener ( air . Event . SELECT, f ileNew) ; 
var sepl = f ileSubmenu . addltem (new air . NativeMenuItem ( " " , 

true) ) ; 

var saveFileltem = f ileSubmenu . addltem (new air. 

NativeMenuItem ( "Save" ) ) ; 
saveFileltem. addEventListener ( air . Event . SELECT, 

f ileSave) ; 

var sep2 = f ileSubmenu . addltem (new air . NativeMenuItem ("" , 
true) ) ; 

var exitFileltem = f ileSubmenu . addltem (new air. 

NativeMenuItem ( "Exit" ) ) ; 
exitFileltem. addEventListener ( air . Event . SELECT, 

fileExit) ; 
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f ileSubmenu : NativeMenu = new NativeMenu () ; 
newCommand : NativeMenuItem = f ileSubmenu . addltem (new 
NativeMenuItem («New») ) ; 
newCommand. addEventListener (Event . SELECT, fileNew) ; 
var sepl : NativeMenuItem = f ileSubmenu . addltem ( new 

NativeMenuItem («B» , true)); 
var saveCommand : NativeMenuItem = f ileSubmenu . addltem (new 

NativeMenuItem («Save») ) ; 
saveCommand. addEventListener (Event . SELECT, fileSave) ; 
var sep2 : NativeMenuItem = f ileSubmenu . addltem ( new 

NativeMenuItem («B», true)); 
var exitCommand : NativeMenuItem = f ileSubmenu . addltem (new 

NativeMenuItem («Exit») ) ; 
exitCommand. addEventListener (Event . SELECT, fileExit) ; 
return f ileSubmenu; 



Adding keyboard shortcuts to menu items 

You can add keyboard shortcuts (or accelerators) to your menu items to 
enable users to select a menu command directly through the keyboard rather 
than navigate the menu. 

A keyboard shortcut normally consists of two parts: a primary (or normal) 
key plus one or more modifier keys (such as Shift, Alt, Ctrl, and, for Mac 
users, Command [§§]). Take the familiar Paste command as an example. 
Under Windows, the keyboard shortcut is Ctrl+P. Under Mac OS X, the 
shortcut is §§+P. 

Adobe AIR has a default modifier key when running under Windows and 
Mac — the Ctrl key for Windows and §§ key for Mac. Each of these is 
automatically added as a modifier key unless you specify otherwise. 

Keyboard shortcuts are applicable only to application and window menus. 
Setting the primary key 

To set the key for a NativeMenuItem, assign a single character string to its 
keyEquivalent property. For example: 

f ileNewItem. keyEquivalent = "n" ; 

The lowercase n in this code assigns Ctrl+N as a shortcut key for the 
f ileNewItem menu item for Windows; it assigns §§+N under Mac. 
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If you use an uppercase letter, the Shift key is added as one of the modifiers. 
Therefore, the following: 

^^wltem. keyEquivalent = "N" ; 

assigns the shortcut keys of Shift+Ctrl+N (Windows) and Shift+3§+N (Mac). 

Setting the modifier keys 

To change the set of modifiers, assign the keyEquivalentModif iers array 
property one or more of the following values: 

f air . Keyboard . CONTROL 

air . Keyboard . COMMAND 
v 0 air . Keyboard . SHIFT 

air . Keyboard . ALTERNATE 

In ActionScript, you want to lose the initial air . reference. 

Because the property is an array type, you can add multiple modifiers inside 
the brackets. For example, to set Ctrl+Alt+N, you use 

f ileNewItem. keyEquivalent = "N" ; 

fileNewItem. keyEquivalentModif iers = [air .Keyboard. 
CONTROL+air . Keyboard . ALTERNATE ] ; 

When you change the keyEquivalentModif iers property, the default 
modifier values are overwritten, so you need to include the Ctrl or §§ key as 
part of the new modifier array. 



Adding mnemonic key assignments 

Both Windows and Mac allow users to access and navigate menus through 
the keyboard through what is known as mnemonics. 

On Windows, a menu command is assigned a mnemonic, which is usually the 
first character of the label. If that character is already used by another item, 
then the next significant character is used. A user is then able to select the 
menu command by pressing and holding the Alt key (to access the window 
menu) while then pressing the mnemonic key. The mnemonic key is often 
underlined (for example, File). 



DropBook 
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On Mac, the mnemonic is slightly different. After one of the top-level applica- 
tion menus is selected, a user types the first letter or two of the command. 
,est match is highlighted. If that's the desired item, press Return to 
item. 



To assign a Windows mnemonic key, you specify the zero-based index of the 
desired character inside the string. The first character is 0, the second 1, and 
so on. Therefore, to assign the F as the mnemonic key for the File command, 
for example, you use the following: 

f ileMenuItem . mnemoniclndex = 0; 



Selecting and deselecting menu items 

You may wish to use a menu command to show the state of your application, 
such as whether a toolbar or status bar is visible. A check mark appearing 
next to the label means that the item is selected and is the standard way to 
indicate an "on" or "true" state. To display a check mark: 

viewStatusBarltem. checked = true; 

To remove the check mark: 

viewStatusBarltem. checked = false; 



Disabling and enabling menu items 

Menu items can be disabled, causing the item to be grayed out. To disable 
a menu item, use the enabled property of a NativeMenultem. Here's an 
example: 

editCutltem. enabled = false; 

When selected, disabled menu items do not trigger a select event. 

See the section "Updating menus before they display," later in this chapter, 
for more on working with the enabled property. 
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Attaching an object to a menu item 



take advantage of the data property of a NativeMenuitem instance 
i data or an object to it. A common example in which this storage 
mechanism can come in handy is for a Recent Documents submenu. You can 
assign a File object to the associated menu item and then open the File 
instance when the menu item is selected. For example, here's a JavaScript 
snippet that assigns an image to the data property of a recent item: 

var imgFile = air .File. applicationStorageDirectory. 

resolvePath ( "wallpaper-1 . jpg" ) ; 
recentlteml . data = imgFile; 



Setting the Application, WindouJ, 
Pop -Up, and Context Menus 

You can set NativeMenu objects to the application, window, pop-up, and 
context menus. (You can also assign them to the taskbar icon and Dock icon 
menus as well, but I cover that later in the chapter.) 

Before assigning application and window menus, you first want to check to 
see whether the OS that the app is running on supports the associated menu. 
Therefore, evaluate the OS before making these menu assignments. 



Setting a Window menu (Windows) 

A window menu is supported on the Windows OS, but only for windows that 
have system chrome. Therefore, you want to perform two checks before 
assigning the window menu. In JavaScript, the code to perform these checks 
is as follows: 



if (air .NativeWindow. supportsMenu && 

nativeWindow . systemChrome != air. 

NativeWindowSystemChrome .NONE) { 
nativeWindow . menu = rootMenu; 

} 
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tiveWindow. supportsMenu && 
nativeWindow . systemChrome ! = 

NativeWindowSystemChrome .NONE) { 
nativeWindow . menu = rootMenu; 



Setting an application menu (Mac) 

To set the application menu for Mac OS in JavaScript, use this code: 

if (air .NativeApplication. supportsMenu) { 
air . NativeApplication . menu = rootMenu; 

} 

In ActionScript, use this code to set the application menu: 

if (NativeApplication. supportsMenu) { 

NativeApplication . nativeApplication .menu = rootMenu; 

} 



Setting a context menu 

A context menu is a menu that you can add to your app that is context aware — 
in other words, the menu choices that are displayed are applicable to that 
particular UI control or part of the app in which the user is working. It is 
accessible in your app by right-clicking an on-screen object. 



Setting a context menu in an HTML app 

For HTML apps, you can set a NativeMenu instance as the context menu for 
an HTML element. To do so, you begin by adding an event handler to the ele- 
ment's oncontextmenu event, as follows: 



<div id=" canvas" oncontextmenu=»displayContextMenu 
( event ) >» 

<p>Content is good. </p> 
</div> 



Next, define the event handler: 



function displayContextMenu (event) { 
event . preventDef ault ( ) ; 
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rootMenu . display (window. nativeWindow. stage, event . 
clientx, event . clientY) ; 

DropBooks 

Because text selections and images have their own default menus, you can 
disable any built-in menus by calling preventDef ault ( ) . The display ( ) 
method of the NativeMenu instance rootMenu is called, using the stage 
object and the mouse x,y coordinates received from the event parameter. 

You can prevent text selection (and the text selection context menu from 
being displayed) by adding the style rule -khtml-user-select :none. This 
WebKit extension selector disallows text selections. 

Setting a context menu in Flex 

In Flex Builder, every mx : UI element contains a contextMenu property. You 
can assign a NativeMenu menu instance to this property either in your code 
or in the designer. 

Using ContextMenu and ContextMenultem 

When creating AIR apps in Flex and Flash, you can also use ContextMenu 
and ContextMenultem to create context menus. However, ContextMenu 
and ContextMenultem are used primarily when you need to output to a 
SWF for in-browser use, because Flash Player doesn't support NativeMenu 
and NativeMenultem. Therefore, if you're focused on developing AIR 
apps and not Flash media, I recommend sticking with NativeMenu and 
NativeMenultem. 



Setting a pop-up menu 

As are context menus, pop-up menus are accessible anywhere inside sand- 
boxed content of your app by right-clicking an on-screen object. You can 
display a NativeMenu instance as a pop-up simply by calling its display ( ) 
method. 

In an HTML application, you can trap for the onmouseup handler: 

<div id="canvas" onmouseup= "displayPopupMenu (event) "> 

<p>Content is good. </p> 

</div> 

The handler then calls the display ( ) method of the NativeMenu instance 
named popupMenu: 
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function displayPopupMenu ( event ) { 
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pMenu . display (window. nativeWindow. stage, event . 
clientx, event. client 

} 



In Flex, you can usually get the functionality you're looking for by 
assigning a NativeMenu instance to the contextMenu property of the 
mx : WindowedApplication element. But you can also show a pop-up menu 
anywhere in your code simply by calling the display ( ) method: 

private function onMouseClick ( event :MouseEvent) :void { 
popupMenu . display (event . target . stage, event . stageX, 
event . stageY) ; 

} 



Handling Menu Events 

As I mention earlier in the chapter, NativeMenu and NativeMenultem 
objects dispatch select and displaying events. To make menu items 
functional, you need to respond to these events. In this section, I walk you 
through how to add support in your apps. 

Responding to menu selections 

NativeMenultem commands are the only part of a menu that can respond 
to a user selection. This makes sense because the root menu, submenus, and 
separators exist only to allow the user to easily navigate a logical grouping of 
selectable menu commands. 

You can respond to select events directly from each menu command by adding 
an event listener (also called an event handler). (See Chapter 6 for more on event 
listeners.) The following JavaScript example assigns the f ileNew ( ) function to 
serve as the select event handler for the newFileitem menu command: 

newFileltem. addEventListener (air . Event . SELECT , fileNew) ; 

However, because select events of menu items bubble up to the menu, you 
can also listen for all select events in the menu. When you do so, you can 
use the target property of the event object to determine the specific menu 
command that was selected. 

The following code assigns the selectTrapper ( ) function as the official 
event listener for rootMenu, which is a top-level menu used throughout the 
project. Here's the JavaScript version: 
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function selectTrapper (event) { 

mr menultem = NativeMenuItem (event . target ) ; 

t( menultem. label + " has been selected, so don't 
try to stop it!"); 



rootMenu . addEventListener (air . Event . SELECT, 
selectTrapper) ; 

Here's the ActionScript version: 

public function selectTrapper (evt : Event) : void { 
var menultem : NativeMenuItem = evt. target as 

Na t i veMenu 1 1 em ; 
mx . controls .Alert . show ( menultem. label + " has been 
selected, so don't try to stop it!"); 

} 

rootMenu . addEventListener (Event . SELECT, selectTrapper) ; 

When the application runs, the selectTrapper ( ) function will serve as the 
handler for all menu commands. 

If you add listeners to both the NativeMenuItem and its NativeMenu con- 
tainer, both event handlers will be triggered. The NativeMenuitem's select 
event is dispatched first and then the event bubbles up to its parent. If you 
have a listener at the container level, it will be called as well. 

Updating menus before they display 

Menus and menu items also dispatch a displaying event just before the 
menu is displayed on-screen. By attaching a listener to this event, you can 
update the contents of a menu or the state of a menu item before the user 
sees it. For example, the following code sample updates the enabled state 
of a menu item depending on settings stored in an object called appProper- 
ties. In JavaScript, you write: 

rootMenu . addEventListener ( air . Event . DISPLAYING, 
updateMenuState) ; 

function updateMenuState (event) : void { 

var menultem = NativeMenuItem (event . target ); 0 
if (menultem. label = 'Allow Updates') { 

menultem. enabled = appProperties . allowUpdates ; 

} 

if (menultem . label = 'Offline Mode') { 

menultem . enabled = appProperties . of flineMode; 

} 

} 



DropBooks 
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In ActionScript, you write it this way: 
potMenu . addEventListener (Event . DISPLAYING, 
updateMenuState) ; 



public function updateMenuState (evt : Event) :void { 
var menultem : NativeMenuItem = evt. target as 

Nat i veMenu Item; 
if (menultem. label = 'Allow Updates') { 

menultem. enabled = appProperties . allowUpdates ; 

} 

if (menultem. label = 'Offline Mode') { 

menultem. enabled = appProperties .of flineMode; 

} 



The FlexNativeMenu Alternative 



Flex developers can use the 
mx : FlexNativeMenu component as 
an alternative to working directly with 
NativeMenu. mx : FlexNativeMenu 
serves as a nonvisual wrapper for 
NativeMenu, allowing you to interact with 
native menus in your MXMLfile much the same 
as you would with Flex's other visual menu 
components. For example, the following code 
defines a root menu: 

<mx: FlexNativeMenu id="rootMenu" 

dataProvider=" {rootMenuData) " 

labelField= " Olabel " keyEquivalentField= " @ 
key" showRoot=" false" /> 

The dataProvider property points to an 
XML hierarchy of menu items that I define as 
follows: 

<mx:XML format="e4x" id=" rootMenuData "> 
<root> 

<menuitem label="_File"> 

<menuitem label="_New" key="n" 

ctrlKey="true" cmdKey="true" /> 
<menuitem type=" separator "/> 
<menuitem label="_Save" key="s" 
ctrlKey="true cmdKey="true" /> 
<menuitem type= " separator " /> 
<menuitem label="Exit"/> 
</menuitem> 



<menuitem label="_Edit"> 

<menuitem label="_Undo" key="z" 

ctrlKey= " true" cmdKey= " true" /> 
<menuitem label="_Redo" key="y" 

ctrlKey= " true" cmdKey= " true" /> 
<menuitem type= " separator " /> 
<menuitem label="Cut" key="x" 

ctrlKey= " true" cmdKey= " true" /> 
<menuitem label= "_Copy" key="c" 

ctrlKey= " true" cmdKey= " true" /> 
<menuitem label="_Paste" key="v" 

ctrlKey= " true" cmdKey= " true" /> 
</menuitem> 

<menuitem label="_Help"> 

<menuitem label="_About MyApp"/> 
</menuitem> 

</root> 
</mx:XML> 

You can attach an event listener to the 
FlexNativeMenu instance much the same 
as you would with NativeMenu: 

rootMenu . addEventListener ( FlexNat 
iveMenuEvent . ITEM_CLICK, 
rootMenuHandler) ; 

See http : / / livedocs . adobe . com/ 
flex/ 3 /html /help .html? content 
=FlexApolloComponents_10 .html 
for more complete details on working with the 
mx : FlexNativeMenu component. 
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Windows and Mac OS X each have dock areas that display icons of opened 
applications. 

Windows has two areas: 

r* Taskbar: Displays currently running apps as buttons across the bar. 

f> System tray: The notification section of the taskbar, usually located at 
the bottom right of the desktop. It contains icons for access to system 
functions or minimized apps. 

By default, your AIR app displays in the taskbar, not the system tray. 
However, if you add a bitmap array to your app for display as the system 
tray icon, the app moves to the system tray. Although you can't modify the 
taskbar icon or menu, you can customize the system tray icon, icon Tool 
Tip, and icon menu. 

The Mac OS X Dock displays application icons. It's used both to launch apps 
and indicate opened apps by displaying a triangle or dot below the icon. The 
right side of the Dock is used for showing application windows that are open. 

You can customize the Dock icon and icon menu, but app window Dock icons 
always use your application's default icon. 

You can work with the icon and its menu on both Windows and Mac through 

the NativeApplication.nativeApplication. icon property. The 
object type is SystemTrayicon under Windows and Dockicon under Mac. 

Before accessing the icon property, you want to check OS support by 
checking the NativeApplication . supportsSystemTraylcon or 
NativeApplication. supportsDocklcon property. If you attempt to 
access a property specific to SystemTrayicon or Dockicon on an OS that 
doesn't support it, you'll trigger a runtime exception. And that's not good for 
anyone! 



Enabling your app for the 
Windows system tray 

You can transform your application to work in the system tray by assigning 
one or more bitmaps to the NativeApplication . nativeApplication . 
icon . bitmaps array property. If that property is assigned, Adobe AIR 
assumes that you'd like your app displayed in the system tray using the 
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designated bitmap. You can provide one or more image sizes in the array. 
When more than one image is included, AIR displays the image that is most 
ate to the size of system tray icons, typically 16 x 16 pixels. 



The following code shows how to add system tray support. First, assign an 
array of images to the bitmaps property (see the upcoming "Putting it All 
Together with MenuAIR" section for more details on how trayDocklcons is 
loaded): 

air .NativeApplication.nativeApplication. icon. bitmaps = [trayDocklcons] ; 

Next, add the icon menu and Tool Tip: 

if (air. Native-Application. supportsSystemTraylcon) { 

SystemTraylcon (air .Nat iveApplicat ion. nativeApplication. icon) .menu = 
createDockMenu ( ) ; 

SystemTraylcon (air .Nat iveApplicat ion. nativeApplication. icon) . tooltip = 
"MenuAIR Command & Control"; 

} 

Remove the air . for ActionScript. 



Enabling your app for the Mac OS X dock 

By default, the icons you assign in the application descriptor file are used as 
the Dock icon for your application. However, you can also assign a separate 
icon through the air . NativeApplication . nativeApplication . icon . 
bitmaps property. 

AIR automatically defines a Dock icon menu for your app. However, you can 
append additional menu commands above the default menu items. To assign 
a menu for your app's icon on the Mac OS X Dock, use the following: 

if (air. NativeApplication. supportsDocklcon) ) 

Docklcon (air .NativeApplication. nativeApplication. icon) .menu = iconMenu; 

} 

Once again, remove the air . for ActionScript. 



Putting It Alt Together With MertuAlK 

Previous sections of this chapter walk you through the process of creating 
and enabling menus. Here, it's time to get practical. The following sample app 
makes use of the menu-building techniques discussed in this chapter. 
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MenuAW: The HTML Edition 

shows the HTML version of my simple menu demo, MenuAIR. 
Listing 8-1: MenuAIR.html 

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/ 
strict .dtd"> 

<html> 
<head> 

<meta http-eguiv="Content-Type" content=" text /html; charset=iso-8859-l" /> 
<title>MenuAIR</title> 

<script type="text/javascript" src="AIRAliases . js"x/script> 
<script type="text/javascript"> 

window. addEventListener (' load' , initialize, false); 
var contextMenu; 

/** 

* Initializes the app after loading 
*/ 

function initialize)) { 

// Create root menu 
var rootMenu = new air .NativeMenut ) ; 

// Create root submenus 

rootMenu . addSubmenu (createFileMenu ( ) , "File") ; 
rootMenu . addSubmenu (createEditMenu ( ) , "Edit") ; 
rootMenu . addSubmenu ( createViewMenu ( ) , "View" ) ; 
rootMenu . addSubmenu (createHelpMenu ( ) , "Help" ) ; 

// Attach event listener routine to root menu 

rootMenu . addEventListener (air .Event . SELECT, dispatchMenuCommand) ; 

// Assign application menu (Mac OS X) 
if (air.NativeApplication.supportsMenu) { 

air. NativeApplication.nativeApplication. menu = rootMenu; 

} 

// Assign window menu (MS Windows) 
if (air.NativeWindow.supportsMenu) { 
window. nativeWindow. menu = rootMenu; 

) 

// Assign context (right-click) menu 
contextMenu = createContextMenu ( ) ; 

contextMenu . addEventListener (air . Event . SELECT, dispatchMenuCommand) ; 
var iconLoader = new air .Loader () ; 
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iconLoader . contentLoaderlnf o . addEventListener ( air . Event . COMPLETE , 
iconLoadComplete) ; 



// Mac OS X dock support 
if (air. Native-Application. supportsDocklcon) { 

iconLoader . load (new air.URLRequest («. . /icons / 128 .png») ) ; 
air .Docklcon (air .Nat iveApplicat ion. nativeApplicat ion. icon) .menu = 
createDockMenu ( ) ; 

} 

// Windows system tray support 

if (air.NativeApplication.supportsSystemTraylcon) { 
// Load icon image 

iconLoader . load (new air .URLRequest (« . . /icons/ 16 .png») ) ; 
air . SystemTraylcon (air .Nat iveApplicat ion. nativeApplicat ion. icon) .menu = 
createDockMenu ( ) ; 

air . SystemTraylcon (air .Nat iveApplicat ion. nativeApplicat ion. icon) . tooltip 
«MenuAIR Command & Control*; 

} 



} 



* Context menu event handler 
* 

*/ 

function displayContextMenu (event) { 
event .preventDef ault ( ) ; 

contextMenu .display (window. nativeWindow. stage, event . clientX, event . 
clientY) ; 



Fills trayDocklcons with loaded icons 



*/ 

function iconLoadComplete (event) { 

trayDocklcon = event . target . content .bitmapData; 

air .Nat iveApplicat ion. nativeApplicat ion. icon. bitmaps 

} 



[trayDocklcon] 



* createMenuCommand ( ) 

* Creates a «fully loaded» menu command based on parameters 
*/ 

function createMenuCommand (menuContainer, itemLabel, itemKey, itemModif iers, 
itemMnemonic, 
selectHandler) { 
var cmd = air .NativeMenu (menuContainer) . addltem(new air. 

NativeMenuItem( itemLabel) ) ; 
cmd.mnemoniclndex = itemMnemonic; 
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cmd.keyEquivalent = itemKey; 
if ( itemModif iers != null ) { 

id.keyEquivalentModif iers = itemModif iers; 



selectHandler != null ) { 
cmd. addEventListener (air .Event . SELECT, selectHandler) ; 

) 

return cmd; 

} 



j * * 

* createMenuSeparator ( ) 

* Creates a menu separator 
*/ 

function createMenuSeparator (menuContainer) { 

var sep = air. NativeMenu (menuContainer) .addltem(new air.NativeMenuItem(«sep», 
true) ) ; 

return sep; 

} 

/** 

* Creates the File menu for app 

*/ 

function createFileMenu ( ) { 

var mnu = new air .NativeMenu () ; 

createMenuCommand ( mnu, 'New', 'n', null, 0, f ileNew) ; 
createMenuCommand ( mnu, 'Open', 'o', null, 0, null); 
createMenuSeparator (mnu) ; 

createMenuCommand) mnu, 'Save', 's', null, 0, fileSave) ; 
createMenuSeparator (mnu) ; 
// If Mac OS X, then use Quit label 
if (air.NativeApplication.supportsMenu) { 

createMenuCommand! mnu, 'Quit', 'q', null, 0, fileExit); 

} 

// If Windows, then use Exit 

else { 

createMenuCommand! mnu, 'Exit', 'x', null, 0, fileExit); 

} 

return mnu; 

1 



* Creates the Edit menu for app 
*/ 

function createEditMenu ( ) { 

var mnu = new air .NativeMenu () ; 

createMenuCommand) mnu, 'Undo', 'z', null, 0, null); 
createMenuCommand) mnu, 'Redo', 'y', null, 0, null); 



(continued) 
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createMenuSeparator (mnu) ; 

teMenuCommand ( mnu, 'Cut 1 , 'x', null, 2, null); 
teMenuCommand ( mnu, 'Copy 1 , 'C, null, 0, null); 
createMenuCommand ( mnu, 'Paste 1 , 'v', null, 0, null); 
return mnu; 

} 



* Creates the View menu for app 

*/ 

function createViewMenu ( ) { 

var mnu = new air .NativeMenu () ; 

var rulerCommand = createMenuCommand ( mnu, 'Ruler', 'r', null, 0, null); 
rulerCommand. checked = true; 

var statusBarCommand = createMenuCommand! mnu, 'Status Bar', 's', null, 0, 
null) j 

StatusBarCommand. checked = true; 
createMenuSeparator (mnu) ; 

createMenuCommand) mnu, 'Current Status', 'C, [air. Keyboard. ALTERNATE] , 0, 
null) ; 

return mnu; 



* Creates the Help menu for app 
* 

*/ 

function createHelpMenu ( ) { 

var mnu = new air .NativeMenu () ; 

createMenuCommand! mnu, 'Help on MenuAIR' , 'h', null, 0, null); 
createMenuSeparator (mnu) ; 

createMenuCommand) mnu, 'About MenuAIR', '', null, 0, null); 
return mnu; 

} 



I * * 

* Creates a context menu for app 
*/ 

function createContextMenu ( ) { 
var mnu = new air .NativeMenu () ; 

createMenuCommand) mnu, 'Cut', '', null, 2, null); 
createMenuCommand) mnu, 'Copy', '', null, 0, null); 
createMenuCommand) mnu, 'Paste', '', null, 0, null) 
createMenuSeparator (mnu) ; 

createMenuCommand) mnu, 'Refresh Status', '', null, 0, null) 
return mnu; 

) 
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* Creates a dock/system tray icon menu 

on createDockMenu ( ) { 
mnu = new air .NativeMenu ( ) ; 
createMenuCommand ( mnu, 'Current Status 1 , '', null, 0, null); 
createMenuSeparator (mnu) ; 

createMenuCommand) mnu, 'Refresh', '', null, 0, null) 
return mnu; 

} 

* Catch-all menu dispatcher for all menus 

*/ 

function dispatchMenuCommand ( event) { 

var menultem = air .NativeMenuItemfevent . target ) ; 

if ( ! menultem. hasEventListener (' select ') ) { 

alert (menultem. label + « has been selected, so don't try to stop it!»); 

} 

} 

* Simple handlers for certain menu commands 

*/ 

function fileNew( event) { 

alert) «You created a new document. You must be proud!»); 

) 

function fileSave (event) { 

alert) «Save that document before this buggy app crashes!*); 

} 

function fileExit (event) { 

air. NativeApplication.nativeApplication. exit ( ) ; 

} 

</script> 
</head> 

<body oncontextmenu=»displayContextMenu (event ) »> 

<div style=»f ont-f amily : 'Lucida Grande', Verdana, Geneva, Sans-Serif; font- 
size: lOpx; 
text-align: center; vertical-align :middle»> 

<p style=»-khtml-user-select :none;» oncontextmenu=»displayContextMenu( event) ;»>M 
enus are more than just for restaurants anymore !</p> 

</div> 
< /body> 
</html> 
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MenuAtR: The Ftex Edition 

^ |*^ ^^j|<^^^2 provides the full source code of the Flex version of MenuAIR. 
Listing 8-2: MenuAIR.mxml 

<?xml version=" 1 . 0 " encoding="utf-8" ?> 

<mx:WindowedApplication xmlns :mx="http : / /www. adobe . com/2006 /mxml" 

layout=" absolute" height="218" width="346" applicationComplete= 
nitWindow) ) "> 

<mx:Script> 
<! [CDATA [7 



import flash . display . Nat iveMenu ; 
import flash .display . Nat iveMenuItem; 
import flash .display . Nat iveWindow; 
import mx. controls .Alert ; 

private var trayDockIcon:BitmapData; 
/** 

* Initializes the app after loading 
* 

*/ 

private function initWindow) ) :void { 
// Create root menu 

var rootMenu :NativeMenu = new Nat iveMenu () ; 
// Create root submenus 

rootMenu . addSubmenu (createFileMenu ( ) , »File») 
rootMenu . addSubmenu (createEditMenu ( ) , »Edit») 
rootMenu . addSubmenu (createViewMenu ( ) , »View») 
rootMenu . addSubmenu (createHelpMenu ( ) , »Help») 

// Attach event listener routine to root menu 

rootMenu . addEventListener (Event . SELECT, dispatchMenuCommand) ; 

// Assign application menu (Mac OS X) 
if (NativeApplication.supportsMenu) { 

NativeApplication.nativeApplication.menu = rootMenu; 

} 

// Assign window menu (MS Windows) 
if (NativeWindow.supportsMenu && 

nativeWindow. systemChrome != NativeWindowSystemChrome .NONE) { 
nativeWindow.menu = rootMenu; 

) 



// Assign pop-up (right-click) menu 
this . contextMenu = createPopupMenu ( ) ; 
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this . contextMenu . addEventListener (Event . SELECT, dispatchMenuCommand) ; 
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ac OS X dock support 
iNativeApplication.supportsDocklcon) { 
Docklcon(NativeApplication.nativeApplication.icon) .menu = createDockMenu ( ) ; 
} 



// Windows system tray support 

if (NativeApplication. supportsSystemTraylcon && 

nativeWindow.systemChrome != NativeWindowSystemChrome .NONE) { 

if (NativeApplication.supportsSystemTraylcon) { 
var iconLoader: Loader = new Loader)); 

iconLoader . contentLoaderlnf o . addEventListener ( Event . COMPLETE , 

iconLoadComplete) ; 
iconLoader . load (new URLRequest («. . /icons/16 .png») ) ; 
SystemTraylcon (Nat iveApplicat ion. nativeApplicat ion. icon) .menu = 

createDockMenu ( ) ; 
SystemTraylcon (Nat iveApplicat ion. nativeApplication. icon) . tooltip = 

«MenuAIR Command & Control*; 
SystemTraylcon (NativeApplication. nativeApplication. icon) . 

addEventListener (MouseEvent .CLICK, activateApp) ; 
stage .nativeWindow. addEventListener (Nat iveWindowDisplayStateEvent .DISPLAY. 

STATE_CHANGING, diyMinimize) ; 

) 

} 

j * * 

* Fills trayDocklcons with loaded icons 
* 

*/ 

public function iconLoadComplete (event : Event ): void { 
trayDocklcon = event . target . content .bitmapData; 

NativeApplication. nativeApplication. icon. bitmaps = [trayDocklcon] ; 

} 

j -k * 

* Hide app when minimized to system tray (Windows) 

* 

*/ 

public function minimizeToSystemTray (): void { 
stage. nativeWindow. visible = false; 

NativeApplication. nativeApplication. icon. bitmaps = [trayDocklcon] ; 

} 

j * * 

* Show app again after minimize to system tray (Windows) 

*/ 

public function activateApp (evt : Event ): void { 
stage. nativeWindow. visible = true; 
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stage. nativeWindow. orderToFront ( ) ; 

t iveApplicat ion. nativeApplicat ion. icon. bitmaps 



/** 

* Custom minimize event handler (Windows) 

*/ 

private function diyMinimize (displayStateEvent :NativeWindowDisplayStateEvent) 
:void { 

if (displayStateEvent . af terDisplayState == NativeWindowDisplayState . 
MINIMIZED) { 
displayStateEvent .preventDef ault ( ) ; 
minimizeToSystemTray ( ) ; 

} 

} 



* createMenuCommand ( ) 

* Creates a «fully loaded» menu command based on parameters 
* 

*/ 

public function createMenuCommand(menuContainer:NativeMenu, itemLabel : String, 
itemKey:String, 

itemModif iers : Array , itemMnemonic : int , selectHandler : Function) : 
NativeMenuItem { 
var cmd:NativeMenuItem= NativeMenu (menuContainer) . addltem(new 

NativeMenuItem (itemLabel) ) ; 
cmd.mnemoniclndex = itemMnemonic; 
cmd.keyEquivalent = itemKey; 
if (itemModif iers != null ) { 

cmd.keyEquivalentModif iers = itemModif iers ; 

) 

if (selectHandler != null ) { 

cmd. addEventListener (Event . SELECT, selectHandler) ; 

) 

return cmd; 

} 



* createMenuSeparator ( ) 

* Creates a menu separator 
*/ 

private function createMenuSeparator (menuContainer :NativeMenu) : NativeMenuItem 
{ 

var sep :NativeMenuItem= NativeMenu (menuContainer) . addltem (new 
NativeMenuItem(«sep», true)); 

return sep; 

} 
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private function createFileMenu ( ) :NativeMenu { 
var mnu :NativeMenu = new NativeMenu) ) ; 
createMenuCommand ( mnu, 'New 1 , n 1 , null, 0, fileNew) ; 
createMenuCommand ( mnu, 'Open', 'o', null, 0, null); 
createMenuSeparator (mnu) ; 

createMenuCommand! mnu, 'Save', 's', null, 0, fileSave) ; 

createMenuSeparator (mnu) ; 

// If Mac OS X, then use Quit label 

if (NativeApplication.supportsMenu) { 

createMenuCommand) mnu, 'Quit', 'q', null, 0, fileExit); 

} 

//If Windows, then use Exit 
else { 

createMenuCommand! mnu, 'Exit', 'x', null, 0, fileExit); 

} 

return mnu; 



* Creates the Edit menu for app 

*/ 

public function createEditMenu ( ) :NativeMenu { 
var mnu : NativeMenu = new NativeMenu)); 
createMenuCommand) mnu, 'Undo', 'z', null, 0, null); 
createMenuCommand) mnu, 'Redo', 'y', null, 0, null); 
createMenuSeparator (mnu) ; 

createMenuCommand) mnu, 'Cut', 'x', null, 2, null); 
createMenuCommand) mnu, 'Copy', 'c', null, 0, null); 
createMenuCommand) mnu, 'Paste', 'v' , null, 0, null); 
return mnu; 



* Creates the View menu for app 
*/ 

public function createViewMenu ( ) :NativeMenu { 
var mnu:NativeMenu = new NativeMenu ( ) ; 

var rulerCommand:NativeMenuItem = createMenuCommand) mnu, 'Ruler', 'r', 



rulerCommand. checked = true; 

var statusBarCommand:NativeMenuItem = createMenuCommand) mnu, 'Status Bar', 




|tes the File menu for app 



) 



null, 0, null); 



's', null, 0, null); 
statusBarCommand. checked = true; 



(continued) 
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Listing 8-2 (continued) 



} Books 



createMenuSeparator (mnu) ; 

teMenuCommand ( mnu, 'Current Status 1 , 'C, [Keyboard. ALTERNATE] , 0, 
null) ; 

return mnu; 



* Creates the Help menu for app 
* 

*/ 

public function createHelpMenu ( ) :NativeMenu { 
var mnu:NativeMenu = new NativeMenu)); 

createMenuCommand ( mnu, 'Help on MenuAIR' , 'h', null, 0, null); 
createMenuSeparator (mnu) ; 

createMenuCommand) mnu, 'About MenuAIR', '', null, 0, null); 
return mnu; 

j * * 

* Creates a pop-up menu for app 

*/ 

public function createPopupMenu ( ) :NativeMenu { 



var mnu: NativeMenu 


= new 


NativeMenu ( ) ; 




createMenuCommand ( 


mnu, 


'Cut ' 




' ' , null, 2 


, null); 


createMenuCommand ( 


mnu, 


'Copy 




, " , null, 


0, null); 


createMenuCommand ( 


mnu, 


' Paste 


' , " , null, 


0, null) 



createMenuSeparator (mnu) ; 

createMenuCommand) mnu, 'Refresh Status', '', null, 0, null) 
return mnu; 

} 



* Creates a dock/system tray icon menu 

*/ 

public function createDockMenu ( ) :NativeMenu { 
var mnu: NativeMenu = new NativeMenu! ) ; 

createMenuCommand) mnu, 'Current Status', '', null, 0, null); 
createMenuSeparator (mnu) ; 

createMenuCommand) mnu, 'Refresh', '', null, 0, null) 
return mnu; 

) 
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* Catch-all menu dispatcher for all menus 



function dispatchMenuCommand (evt : Event) : void { 
menuItem:NativeMenuItem = evt. target as NativeMenuItem; 

if ( imenuItem.hasEventListener (' select ') ) { 
Alert . show (menultem. label + " has been selected, so don't try to stop 
it ! " ) ; 

) 

} 

j ** 

* Simple handlers for certain menu commands 
* 

*/ 

public function fileNewfevt: Event) : void { 

Alert. show) "You created a new document. You must be proud!"); 

> 

public function f ileSave (evt : Event) : void { 

Alert. show ( "Save that document before this buggy app crashes!"); 

) 

public function f ileExit (evt : Event) : void { 
NativeApplication.nativeApplication. exit ( ) ; 

} 




]]> 

</mx:Script> 



<mx:Label id=»lblApp» text=»Menus aren't just for restaurants anymore! 
verticalCenter=»0» horizontalCenter=»0»/> 



</mx:WindowedApplication> 



When MenuAIR runs under Mac OS X, the main window (see Figure 8-1) is 
displayed, as you would expect without a window menu. However, the Mac 
menu bar displays the new application menu. Figures 8-2, 8-3, and 8-4 show 
the File, View, and Help submenus. Figure 8-5 shows the pop-up menu. 
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The MenuAIR Dock icon shows the custom menu items appended to the 
default menu (see Figure 8-6). 




When MenuAIR runs under Windows, the main window (see Figure 8-7) now 
comes complete with a window menu. The File menu items, shown in Figure 
8-8, provide the Windows-specific shortcut keys. 
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Figure 8.9 shows the tool tip displayed above the app's taskbar icon, and 
Figure 8.10 displays the pop-up menu for the taskbar icon. 
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In this part . . . 

■ n this part, you continue to develop your knowledge 
«fi of the essentials of AIR application development. You 
explore how to interact with the local file system. For 
database applications, I show you how to work with both 
local and remote data sources. ActionScript developers 
will want to know how to access their libraries, so I show 
you how to access libraries in your HTML and Flex apps. 













Chapter 9 

Be a Drag: Interacting with 
the Clipboard and Drag-and-Drop 

In This Chapter 

Exploring how to cut, copy, and paste with the Clipboard 
Adding native drag-and-drop to your apps 
Working with HTML drag-and-drop functionality 



■ ^ne of the advantages that AIR has over browser-based apps is the 
\r ability to interact with other native applications. Yes, you can do some 
cool bleeding-edge inter-application communication techniques. However, 
on a practical, real world basis, you'll find yourself using the Clipboard and 
drag-and-drop for most inter-application data transfer. In this chapter, you 
discover how to work with the Clipboard and drag-and-drop within your AIR 
applications. 



Working ufith the Clipboard 

The Clipboard is one part of the OS that is easily taken for granted these days. 
It's certainly not sexy like drag-and-drop or hip like XML data transfer. Having 
said that, I hasten to add that the good ol' commands Cut, Copy, and Paste 
remain the fundamental means of data interchange between desktop apps. 

As a citizen of the native OS, Adobe AIR enables you to work with the full 
capabilities of the Clipboard through the Clipboard object. Although it's 
easy to think of just Cut/Copy/Paste when working with the Clipboard, the 
Clipboard is also used for drag-and-drop operations. 

What's more, not only can you use the Clipboard to copy and paste text, but 
you can also work with several different data formats, such as images or a file 
list. As a result, you can decide which formats your application will support. 
The [air . ] ClipboardFormats class provides the constants for the various 
data formats supported by AIR. Table 9-1 lists the various formats you can 
support. 
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Table 9-1 


Clipboard Formats 




)KS 


[air . ] ClipboardFormats 


MIME Type 






Constant 






Tavt 
1 UaL 


TEXT FORMAT 


" text/plain" 




HTML 


tl 1 i v lj_i r UI\lXL/\ 1 


"text /html " 




URL 


. URL_F ORMAT 


" text /uri- list 




Bitmap 


B I TMAP_FORMAT 


" image /x-vnd . adobe . 






air .bitmap " 




File list 


FILE_LIST_FORMAT 


"application/x 


-vnd. 






adobe . air . file 


-list" 


Rich 


RICH_TEXT_FORMAT 


Not available in HTML context 


Text 








Format 









Data placed in the Clipboard may have multiple formats, which increases the 
usefulness of the Clipboard data. For example, a fragment of HTML text may 
be placed in the Clipboard by Dreamweaver as html_format and text_ 
format. You can then decide whether to implement support for one or both 
of these data formats. 




You can also implement your own data format for use in the Clipboard to 
transfer objects as references within the same AIR app or serialized copies 
between AIR apps. However, note that you can't paste this data into a non- 
AIR application. For technical details on how to implement custom data 
formats, visit http : / / livedocs . adobe . com/ flex/3 /html /help . 
html?content=CopyAndPaste_6 . html . 



Adding basic cut, copy, and 
paste functionality 

Perhaps the most basic implementation of the Clipboard is to provide 
services that allow you to cut, copy, and paste text-related data. To add this 
functionality to an AIR app, I define three functions for this purpose: 

editCopy ( ) , editCut ( ) , and editPaste ( ) . 

Copt} text to the Clipboard 

Copying text to the Clipboard involves the following code. Here's the 
JavaScript version: 



Chapter 9: Don't Be a Drag: Interacting with the Clipboard and Drag-and-Drop 



var st 

3ooks 

air.Cl 



editCopy ( event) { 

var str = "You're all grown up now, AIR text. You are now heading " 
to Clipboardopolis to make a name for yourself."; 
ipboard.generalClipboard. clear ( ) ; 

ipboard . generalClipboard . setData ( air . ClipboardFormats . TEXT_FORMAT , str ) ; 
} 



The generalClipboard property is used to access the native OS Clipboard. 
The clear ( ) method clears the Clipboard, followed by a setData ( ) com- 
mand that adds the contents of the str variable to the Clipboard, specifying 
its data format with the first parameter. 

Here's an ActionScript version of editCopy ( ) that copies the text selection 
(TextRange object) of an mx : TextArea to the Clipboard: 

public function editCopy (evt : Event ): void { 

var tr:TextRange = new TextRange (taEditor, true); 
var textToCopy: String = tr.text; 
Clipboard. generalClipboard. clear ( ) ; 

Clipboard. generalClipboard. setData (ClipboardFormats .TEXT_FORMAT, 
textToCopy) ; 

} 



Cut text to the Clipboard 

From a Clipboard standpoint, cutting text to the Clipboard is the same task 
as copying it. The only difference is cleaning up the text inside your applica- 
tion. For example, here's an ActionScript version that removes the text inside 
a selection after the selected text is copied to the Clipboard: 

public function editCut(evt: Event) : void { 

var tr: TextRange = new TextRange (taEditor, true); 
var textToCopy: String = tr.text; 
Clipboard. generalClipboard. clear ( ) ; 

Clipboard. generalClipboard. setData (ClipboardFormats .TEXT_FORMAT, 

textToCopy, false) ; 
tr . text = " " ; 

) 



Paste text from the Clipboard 

Retrieving text that is in the Clipboard involves first testing the format of the 
Clipboard contents and making sure that the format is what you expect. If it is, 
you can use getData ( ) to retrieve the contents. In JavaScript, here's a 
function that gets Clipboard text and then displays the result in a message box. 
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function editPaste (event) { 

Clipboard. generalClipboard.hasFormat (air .ClipboardFormats . TEXT_FORMAT ) ) < 
= air. Clipboard. generalClipboard.getData (ClipboardFormats .TEXT_ 
FORMAT) ; 

alert (text) ; 
} 

Here's an ActionScript example that pastes text into a text memo: 

public function editPaste (evt : Event) : void { 

var tr:TextRange = new TextRange (taEditor, true); 

if (Clipboard. generalClipboard.hasFormat (ClipboardFormats . TEXT_FORMAT ) ) { 
var str: String = Clipboard. generalClipboard.getData (ClipboardFormats .TEXT_ 
FORMAT) as String; 
tr.text = str; 

} 



In this example, the Clipboard contents are assigned to the str variable, 
which is then assigned to replace the current text selection (if any). 



Usinq an alternate Clipboard method 
in HTML environments 

The Clipboard object is great for use inside the application sandbox when 
using ActionScript or JavaScript. However, because of security restrictions, 
you can't access the AIR Clipboard object outside the sandbox. 

Coming to the rescue, AIR provides a basic implementation of cut, copy, and 
paste if you're using TextField or HTMLLoader objects or their descen- 
dants; it does this by calling the NativeApplication.nativeApplica- 
tion methods cut ( ) , copy ( ) , and paste ( ) . For example: 

editCopyO { 

air .Nat iveApplicat ion. nativeApplicat ion. copy ( ) ; 

} 

editCutO { 

air.NativeApplication.nativeApplication.cut ( ) ; 

} 

editPaste () { 

air .Nat iveApplicat ion. nativeApplicat ion. paste ( ) ; 

} 

When one of these functions is called, the command is called for the display 
object receiving focus. However, the display object needs to be a TextField 
or HTMLLoader object (or descendant) or the command is ignored. 
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Copying and pasting images 
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The Clipboard can support data formats beyond ordinary text. You can also 
use it to support other formats, such as images. Here's an example of enabling 
an AIR application to support the copying and pasting of images. You still use 

the Clipboard. generalClipboard. setData ( ) and Clipboard. general 
Clipboard. getData ( ) methods as before. You just need to specify the 
different data format to the Clipboard (ClipboardFormats . bitmap_ 
format) and convert the data into the format that the OS expects (for example, 
bitmap data). 



Copying an image 

To copy an image from your app to the Clipboard, you can't just send an 
instance of an image object to the Clipboard using setData ( ) . That's 
not in the expected format if you want to use the image in an image editing 
application, such as Photoshop. Instead, you need to convert the image 
instance into bitmap data, which is represented by the BitmapData class in 
ActionScript. The following code takes an image (named src image) and 
converts it into the more portable BitmapData type: 

var bitmapData: BitmapData = new BitmapData (srclmage .width, srclmage. height ) ; 
bitmapData.draw(srcImage) ; 



After you've converted the image into the appropriate bitmap format, you're 
ready to place the image on the Clipboard: 



Clipboard. generalClipboard. clear ( ) ; 



Clipboard. generalClipboard. setData (ClipboardFormats .BITMAP_FORMAT, bitmapData) ; 



The setData ( ) method specifies that the bitmapData object instance 
should be classified as bitmap_format. 



Pasting an image 

When you paste an image from the Clipboard and put it into a usable format, 
you essentially want to reverse the process of copying an image — retrieve 
the bitmap data and convert it into an image that you can then display in 
your app. 

First, you need to use hasFormat ( ) to determine whether there is a bitmap 
to paste in the Clipboard. If there is, then you need to cast the incoming 
object as BitmapData: 
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if (Clipboard. generalClipboard.hasFormat (ClipboardFormats .BITMAP_FORMAT) ) { 
var bitmapData:BitmapData = 

'board. generalClipboard.getData (ClipboardFormats .BITMAP_FORMAT) as 
BitmapData; 



You can't just add bitmapData to the stage for display. Instead, you need to 
add its bitmapped data into an image instance. To do so, you need to use a 
Bitmap instance as an intermediary format: 



var bitmap: Bitmap = new Bitmap (bitmapData) ; 
var img : Image = new Image ( ) ; 
img . addChi Id ( bi tmap ) ; 



At this point, you just need to determine where to locate the incoming object 
onto the stage (the visible display area of an AIR app). After setting the x and 
y properties, you add img as a child to a Canvas instance: 



img.x = stage. stageWidth/4; 
img.y = stage. stageHeight/4; 
canvas . addChild ( img) ; 




The full source code is shown in Listing 9-1. 



Listing 9-1: ImagePaster.mxn 


ll 








<?xml version=" 1 . 0 " encoding="utf 
<mx:WindowedApplication xmlns:mx= 
layout= " absolute " width= " 500 " 
<mx:Script> 
<! [CDATA[ 


•: 

: 


3"?> 

http : / /www. a 
ieight="400" 


dobe . com/2 0 0 6 /mxml " 
> 





import mx. controls . Image; 



public function editCopy (evt : Event ): void { 

var bitmapData: BitmapData = new BitmapData (srclmage .width, srclmage. 

height) ; 
bitmapData. draw(srclmage) ; 
Clipboard . generalClipboard . clear ( ) ; 

Clipboard . generalClipboard . setData (ClipboardFormats . BITMAP_FORMAT , 
bitmapData, false) ; 

) 



public function editPaste (evt : Event ): void { 

if (Clipboard. generalClipboard.hasFormat (ClipboardFormats .BITMAP_FORMAT) ) { 
var bitmapData: BitmapData = Clipboard. generalClipboard. 

getData (ClipboardFormats .BITMAP_FORMAT) as BitmapData; 
var bitmap:Bitmap = new Bitmap (bitmapData) ; 
var img : Image = new Image ( ) ; 
img . addChi Id ( bi tmap ) ; 
img.x = stage. stageWidth/4; 
img.y = stage.stageHeight/4; 
canvas . addChild ( img) ; 

} 
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<mx : Canv 



ipt> 

:Canvas id=»canvas» width=»100%» height=»100%» backgroundColor=»#FFFFFF»> 
<mx:Button x=»0» y=»0» label=»Paste» id=»btnPaste» click=»editPaste (event ) » /> 
<mx:Image id=»srclmage» source=»door .png» x=»40» y=»191» 
click=»editCopy (event ) »/> 

</mx:Canvas> 

</mx:WindowedApplication> 



Don't Be a Drag: Adding Drag-and-Drop 

Just over a decade ago, drag-and-drop gestures were innovative and ground- 
breaking in UI design — enabling users to perform an action simply by 
moving their mouse rather than clicking a button or menu item. Although 
drag-and-drop may not seem to be cutting-edge technology these days, it has 
proven itself to be far more than a fad or gimmick. With its usefulness and 
ease of use, drag-and-drop should be something all AIR developers should 
consider enabling in their application. 

You can implement drag-and-drop within your application, such as the ability 
to move display objects around on your stage. You can also add drag-and-drop 
support to exchange data between other native apps. Consider a typical 
scenario. Suppose you want to drag text from a Web page and drop it into 
your AIR app. When the text is dragged outside the browser, information 
about the text data is placed into the Clipboard, which is then used by the 
AIR app during the drag-and-drop process. 

For a given drag-and-drop operation, you have two important actors — the 
drag initiator and the drop target. The drag initiator is the source display 
object selected by the user to be dragged and dropped. The drop target is 
the object on which the user drops the drag initiator. You need to explicitly 
enable an object to initiate a drag operation or receive a drop. 

A drag-and-drop sequence occurs in three distinct actions: 

v 0 Start drag: A drag sequence begins when a user clicks an object and 
holds the mouse button down (the drag initiator) and then moves the 
mouse while continuing to hold the mouse button down. 

Dragging: While the mouse button is down, the user drags the clicked 
object to another part of the app, to another native application, or to the 
desktop. 

Drop: A drag-and-drop sequence ends when a user releases the mouse 
over a valid drop target. 
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Most of the AIR functionality I talk about in this book is identical whether 
you're creating an app using HTML, Flex, or Flash. However, here's one 
ljc^ jujjjere you want to implement drag-and-drop differently depending on 
you're working in an HTML, Flash, or Flex environment. 



For HTML apps, you use the HTML drag-and-drop API, which is nicely 
integrated with the Document Object Model (DOM). Technically, you could 
use the AIR drag-and-drop API calls, but these are less effective than the 
HTML drag-and-drop API inside the HTML environment. 

In Flex and Flash, you want to use the NativeDragManager class and work 
with the nativeDragEnter, nativeDragOver, and nativeDragDrop 
events when you want to perform drag-and-drop actions with other native 
apps. 

In this section, I show you how to work with drag-and-drop in Flex and Flash, 
and then in HTML-based apps. 



Adding draq-and-dvop in Ftex and Flash 

A typical drag-and-drop action for any native application that works with text 
is the ability to drag text onto the app and paste the text into the appropri- 
ate text control. Another common action is dragging a file from the Windows 
Explorer or Mac OS X Finder window and dropping it into an app. I show 
you how to add support for these two drag-and-drop actions in a Flex-based 
sample AIR app named AIRWrite. (The ActionScript code would be equivalent 
in a Flash app.) 

To make the application serve as a drop target for drag operations, you begin 
by adding event listeners for the native_drag_enter and native_drag_ 
drop events. You add these inside an init ( ) function that is triggered when 
the app is done loading: 

addEventListener ( Nat iveDragEvent . NATIVE_DRAG_ENTER , onDragln) ; 



addEventListener (Nat iveDragEvent . NATIVE_DRAG_DROP , onDragDrop) ; 

The onDragln ( ) function serves as the event handler for the native_ 
drag_enter event. Its purpose is to determine the drag-and-drop actions 
that the app will support. For AIRWrite, you want to support text and file 
drop actions. 

The first task is to define the dropAction, which could be to either copy, 
move, or link. The following code chooses copy: 

NativeDragManager. dropAction = NativeDragActions .COPY; 
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Next, you need to check the format of the Clipboard data. If it is 
ClipboardFormats . text_format, you want to accept the drag action: 



if (event .clipboard. hasFormat (ClipboardFormats . TEXT_FORMAT ) ) { 
Nat iveDragManager . acceptDragDrop ( this ) ; 
) 

You also want to check to see whether incoming data is of 
ClipboardFormats . file_list_format. If it is, you want to accept the 
drag action. However, because AIRWrite works as an editor only with a single 
text file, you want to support only one file being dragged in, not multiple 
ones. Here's the ActionScript code: 

if (event .clipboard. hasFormat (ClipboardFormats .FILE_LIST_FORMAT ) ) { 

var files:Array = event . clipboard. getData (ClipboardFormats .FILE_LIST_ 

FORMAT) as Array; 
if (files. length == 1) { 

Nat iveDragManager . acceptDragDrop ( this ) ; 

) 

You use the getData ( ) method to return the file list as an Array type 
instance. After you do that, you check the length of the array to determine 
whether to accept the drag action. 

The onDragDrop ( ) function handles the NativeDragEvent . NAT I VE_ 
drag_drop events that are dispatched by the app. Depending on the needs 
of the app, you may need to handle incoming text data. If so, begin by check- 
ing to see whether the data being dropped is ClipboardFormats . text_ 
format. If so, you can assign the text to a String variable: 

if (event .clipboard. hasFormat (ClipboardFormats . TEXT_FORMAT ) ) { 

var txt:String = String (event . clipboard. getData (ClipboardFormats . TEXT_FORMAT , 
ClipboardTransf erMode . ORIGINAL_PREFERRED) ) ; 

} 



You then place the contents of txt to the drop target in your app. 

If you're instead using an mx : TextArea for the text editor for AIRWrite, it 
handles the drop action for text data for you automatically. In other words, 
you don't even need to deal with text data in the onDragDrop ( ) if the built- 
in drop action suits your needs. 

However, you do need to account for ClipboardFormats . FILE_LIST_ 
format and open the file that is being dropped onto the target: 

if (event .clipboard. hasFormat (ClipboardFormats .FILE_LIST_FORMAT) ) { 

var array:Array = event . clipboard. getData (ClipboardFormats .FILE_ 

LIST_FORMAT) as Array; 
file = File(array[0] ) ; 
onFileSelect (event) ; 
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The first item in the file list array is assigned to the file variable. The onFile 
Select ( ) function is called, which is AIRWrite's handler for opening text files: 




iblic function onFileSelect (evt :Event) :void { 
var fs :FileStream = new FileStream( ) ; 
fs .openAsync (file, FileMode.READ) ; 
fs .addEventListener (Event .COMPLETE, onFileRead) ; 
fs .addEventListener (IOErrorEvent . IO_ERROR, onlOReadError) ; 
isDirty = false; 
isNewFile = false; 
this. status = 

title = "AIRWrite - " + file. name; 
taEditor . setFocus ( ) ; 



See Chapter 10 for more details on how to read text files. 

Figures 9-1 and 9-2 demonstrate the drag action of text data. Figures 9-3 and 
9-4 show a file being dragged onto the editor. 
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For HTML apps, you'll want lo use the HTML drag-and-drop API, which is 
nicely integrated with the DOM. Technically, you could use the 
N at iycD rag-Manager and NativeDragLvc-nt part of the AIR API, but these arc 
less effective inside of the HTML environment. 

In Flex and Flash, you will want 10 use the NativcDragManager class and 
work with the na.tivcDragEntcr , nativcDragQvcr , and nativcDragDrop . events. 
In Flex, you can also use its built-in drag-and-drop API that is appropriate for 
developing both desktop AIR apps and in-browscr web apps. 

In this section, I'll show you how to work with drag-and-drop in Flex and then 
HTML-based apps. 



Adding drag-and-drop in Flex 



A typical drag-and-drop action for any native app that works with text is the 
bility to drag text onto the app and have the text pasted into the appropriate 
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Because 1 want to the app to be a drop target for drag operations, I want lo 
begin by adding event listeners Cor ihc NATIVE DRAG ENTER and 
NATIVE DRAG DROP events. I add these inside of an function that is 
triggered when the app is done loading: 
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Figure 9-1: 

Drag action 
begins in 
Microsoft 
Word. . . 



D Move lo where?" 



The pnDraglnO function serves as the event handler for the 
NATIVE DRAG ENTER event. Its purpose is to determine the drag-and- 
drop actions that the app will support. For AIRWrite, I want to support text 
and file drop actions. 

The first task is to define the dropAclion. which could be cither copy, move, 
or link. I'll choose copy: 

Next, I need to check the format of the Clipboard data. If it is 
CiipboardFormat s .TEXT FORMAT , then I want to accept the drag action: 
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Figure 9-3: 

File drag 
action 
begins in 
the Mac OS 
X Finder. . . 
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Listing 9-2 provides the full source code for AIRWrite.mxml. 
-2: AIRWrite.mxml. 



<?xml version=" 1 . 0 " encoding="utf -8 " ?> 
<mx:WindowedApplication xmlns :mx="http : / /www. adobe . com/2006 /waul" 
layout=" absolute" width="764" height="454" 
applicationComplete="init ( ) " styleName="sansChrome" 
backgroundGradientAlphas= "[0.3, 0 . 3 ] " > 



<mx:Style> 

. sansChrome { background-color: 
</mx:Style> 



<mx:Script> 
<! [CDATA [ 

import mx. controls .Alert ; 
import flash. display. Nat iveMenu ; 
import f lash. display .Nat iveMenuI tern; 
import mx. events.*; 

import flash. desktop .Nat iveDragManager; 
import flash. events .Nat iveDragEvent ; 
import flash. desktop. Clipboard; 
import flash . desktop . ClipboardFormats ; 
import flash. filesystem. File; 
import flash. filesystem. FileMode; 
import flash. filesystem. FileStream; 
import mx. controls . textClasses . TextRange; 

private var file: File- 
public function onDragln (event :NativeDragEvent ): void { 

// Define drop action - copy, move, link? 

NativeDragManager.dropAction = NativeDragActions .COPY; 

// Check to see if the data is TEXT_FORMAT 

if (event .clipboard. hasFormat (ClipboardFormats . TEXT_FORMAT ) ) { 
Nat iveDragManager . acceptDragDrop ( this) ; 

} 

else if (event .clipboard. hasFormat (ClipboardFormats .FILE_LIST_FORMAT ) 
) { 

var files:Array = event . clipboard. getData (ClipboardFormats .FILE_LIST_ 

FORMAT) as Array; 
if (files. length ==1) { 

NativeDragManager . acceptDragDrop ( this) ; 

) 

} 



public function onDragDrop (event : Nat iveDragEvent) :void { 

if (event .clipboard. hasFormat (ClipboardFormats . TEXT_FORMAT ) ) { 
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var text:String = String (event . clipboard. getData (ClipboardFormats . 
TEXT_FORMAT, 
CI ipboardTrans f erMode . ORIGINAL_PREFERRED } ) ; 



else if (event .clipboard. hasFormat (ClipboardFormats .FILE_LIST_FORMAT) ) 



{ 

var array:Array = event . clipboard. getData (ClipboardFormats .FILE. 

LIST_FORMAT) as Array; 
file = File(array[0] ) ; 
onFileSelect (event) ; 



private function init():void { 
file = new File ( ) ; 

addEventListener (NativeDragEvent .NATIVE_DRAG_ENTER, onDragln) ; 
addEventListener (NativeDragEvent .NATIVE_DRAG_DROP, onDragDrop) ; 



public function onFileSelect (evt : Event ): void { 
var fs :FileStream = new FileStream( ) ; 
fs .openAsync (f ile, FileMode.READ) ; 
fs. addEventListener (Event. COMPLETE, onFileRead) ; 
fs. addEventListener (IOErrorEvent . IO_ERROR, onlOReadError) ; 
isDirty = false; 
isNewFile = false; 
this. status = ""; 

title = "AIRWrite - " + filename; 
taEditor . setFocus ( ) ; 



private function onFileRead (evt :Event) : void { 
var fs :FileStream = evt. target as FileStream; 
var str:String = f s . readUTFBytes ( f s .bytesAvailable) ; 
taEditor. text = str; 
f s . close ( ) ; 



private function onlOReadError (evt : Event ): void { 

Alert . show ( "Something wacky happened. We are unable to open " + file. 



private function onlOWriteError (evt :Event) :void { 

Alert. show ("We are really sorry, but the file cannot be saved. It's not 




} 



} 



} 



nativePath, "Error", Alert. OK, this); 



our fault. . .really! 



Error", Alert. OK, this); 



} 



]]> 



(continued) 
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</mx:Script> 



dBooks 



!xtArea id="taEditor" x="0" y="0" width="100%" height="100%" 
backgroundAlpha= "0.8" 
fontFamily=" Courier New" fontSize="14" backgroundColor="#000000" 
color="#FFFFFF" /> 

<mx:Canvas x="352" y="169" width="200" height="200" backgroundColor="#982A2A" 
label="ddd"> 

</mx:Canvas> 
</mx:WindowedApplication> 



If you want to perform drag-and-drop actions with images, you can program 
your application in much the same manner, with one difference. Although 
the mx : TextArea and related text controls handle the drag initiator action 
automatically, you need to explicitly add code to enable drag actions when 
working with a nontext display object such as mx : image. 

Suppose you'd like to drag an image into other native apps as well as accept 
new images from outside the application. Here's a very basic UI: 

<mx:Canvas id="canvas" width="100%" height="100%"> 
<mx:Image id="doorImage" source="door .png" /> 
</mx:Canvas> 



To begin, you'd want to add event listeners when the app loads, just as you 
did in the AIRWrite example: 



private function init():void { 



addEventListener ( Nat iveDragEvent . NATIVE_DRAG_ENTER , onDragln) ; 
addEventListener (Nat iveDragEvent . NATIVE_DRAG_DROP , onDragDrop) ; 



} 



These event handlers are designed to enable the app as a drop target. The 
onDragln ( ) function simply checks to see whether the incoming drop initia- 
tor is a bitmap. If it is, it's accepted. The code is as follows: 

public function onDragln (event : Nat iveDragEvent ): void { 
NativeDragManager.dropAction = NativeDragActions .COPY; 
if (event .clipboard. hasFormat (ClipboardFormats .BITMAP_FORMAT) ) { 
NativeDragManager . acceptDragDrop ( this) ; 

} 

} 

The onDragDrop ( ) function uses getData ( ) to retrieve the bitmap data. A 
new image instance is then created using that bitmap data and is added as a 
child to the Canvas object: 
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public function onDragDrop (event :NativeDragEvent) :void { 

if (event .clipboard. hasFormat (ClipboardFormats .BITMAP_FORMAT) ) { 

bitmapData :BitmapData = event . clipboard. getData (ClipboardFormats . 
BITMAP_FORMAT) as BitmapData; 
var bitmap:Bitmap = new Bitmap (bitmapData) ; 
var img : Image = new Image ( ) ; 
img . addchild (bitmap) ; 



img.x = event. localX 
img.y = event. localY 
canvas . addchild ( img) 



} 



Figures 9-5 and 9-6 demonstrate the drag-and-drop sequence. I start out 
dragging an image from Photoshop and wind up dropping it onto my AIR app. 




ImageDrager 




Figure 9-6: 

The dragged 
image is 
dropped 
onto an 
AIR app. 




To enable the mx : image object as a drag initiator for other native applications, 
you need to add a handler for the mouseMove event: 
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<mx:Image id="doorImage" source="door.png" mouseMove="onMouseMove (event) " /> 

useMove ( ) function is defined as follows: 



private function onMouseMove (event :MouseEvent) : void { 
var draglnitiator : Image=Image (event . currentTarget) ; 
var transferClipboard: Clipboard = new Clipboard!); 

var bitmapData:BitmapData = new BitmapData (doorlmage .width, doorlmage. 

height) ; 
bitmapData. draw (doorlmage) ; 

transferClipboard. setData (ClipboardFormats .BITMAP_FORMAT, bitmapData) ; 
Nat iveDragManager .doDrag (draglnitiator, transferClipboard, bitmapData, new 
Point (-mouseX, -mouseY) ) ; 

} 



The image being dragged is assigned to the draglnitiator instance. 
A Clipboard instance named transferClipboard is created, which 
serves as the container for the data the app will transfer. The bitmapData 
instance will store the bitmap image. The image is then added to transferClip- 
board through its setData ( ) method. Finally, the NativeDragManager . 
doDrag ( ) method is called to begin the drag and provide this data to out- 
side applications if the mouse moves beyond the window. 

Figure 9-7 shows the image being dragged in the AIR app, and Figure 9-8 
shows the end result when the image is dropped into Microsoft Word. 



ft O ImageDrager 




Figure 9-7: 

Image 
dragged 
from the 
AIR app. 
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Figure 9-8: 

Dragged 
image is 
dropped into 
Microsoft 
Word. 




Listing 9-3 shows the full source code for this application. 



Listing 9-3: ImageMover.mxml. 

<?xml version=" 1 . 0 " encoding="utf-8" ?> 

<mx:WindowedApplication xmlns :mx="http : //www. adobe . com/2006 /mxml" 
layout= " absolute " 
applicationComplete="init ( ) "> 



<mx:Script> 



(continued) 
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<! [CDATA[ 

//Import classes so you don't have to use full names, 
import flash. events .MouseEvent ; 
import flash. desktop .Nat iveDragManager; 
import flash. events .Nat iveDragEvent ; 



private function init():void { 

addEventListener (Nat iveDragEvent .NATIVE_DRAG_ENTER, onDragln) ; 
addEventListener (NativeDragEvent .NATIVE_DRAG_DROP, onDragDrop) ; 

) 

public function onDragln (event : Nat iveDragEvent ): void { 
NativeDragManager.dropAction = NativeDragActions .MOVE; 
if (event .clipboard. hasFormat (ClipboardFormats .BITMAP_FORMAT) ) 
Nat iveDragManager . acceptDragDrop ( this ) ; 

} 

} 



public function onDragDrop (event : Nat iveDragEvent) :void { 

if (event .clipboard. hasFormat (ClipboardFormats .BITMAP_FORMAT) ) { 
var bitmapData:BitmapData = event . clipboard. 
getData (ClipboardFormats .BITMAP_FORMAT) as BitmapData; 
var bitmap:Bitmap = new Bitmap (bitmapData) ; 
var img : Image = new Image ( ) ; 
img.addchild(bitmap) ; 
img.x = event. localX 
img.y = event. localY 
canvas . addchild ( img) 



} 



private function onMouseMove (event : MouseEvent ): void { 
var draglnitiator : Image= Image (event . currentTarget) 
var transferClipboard: Clipboard = new Clipboard)); 
var bitmapData: BitmapData = new BitmapData (doorlmage .width, 
doorlmage .height) ; 
bitmapData. draw (doorlmage) ; 

transferClipboard. setData (ClipboardFormats .BITMAP_FORMAT, 
bitmapData) ; 

Nat iveDragManager .doDrag (draglnitiator, transferClipboard, bitmapDa 
ta, new Point (-mouseX, -mouseY) ) ; 

) 



]]> 

</mx:Script> 



< ! — The Canvas is the drag target — > 

<mx:Canvas id="canvas" width="100%" height="100%" backgroundColor="#DDDDDD" 
dragEnter="onDragEnterCanvas (event) ; " 
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dragDrop= " onDragDropCanvas ( event ) ; " > 
<! — The image is the drag initiator. — > 

<mx:Image id="doorImage" source="door.png" mouseMove="onMouseMove (event 
);"/> 



</mx:Canvas> 
</mx:WindowedApplication> 



Adding drag-and-drop functionality 
in HTML apps 

Adobe AIR enables you to take advantage of built-in support for drag-and- 
drop of key elements within the WebKit environment when creating HTML 
apps. These elements include text, images, and URLs. However, you can also 
declare other elements, such as div elements, as draggable by setting the 
-webkit-user-drag CSS property to element. You still need to determine 
how you want to use the draggable elements in the drop target, though. 

In this section's example, I show you how to make various elements drag- 
gable for both inside and outside the AIR app. I then show you how to create 
a drop zone for working with drag-and-drop data. The HTML file that I start 
the example with is as follows: 



<html> 
<head> 

<title>DragMeDropMe</ titl 


e> 


<style> 




#droptarget { 
float : right ; 

backcrronnd-nol or : #999999: 


margin: lOpx; 
padding: lOpx; 
height: 500px; 
width: 3 00px; 
color: white; 

} 




#draginit-text { 
font-size: 18pt; 

} 
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#draginit-div { 
width: 3 00px; 
ight: 2 00px; 
xt-align : center ; 
color: white; 
background-color: #8888£ 
border: lpt solid black; 



</style> 

<script type=»text/ j avascript» src=»AIRAliases . j s»></ 
script> 

<script type=»text/ j avascript»> 

function init() { 

// do something, anything 

} 

</script> 
</head> 

<body onload=»init ( ) »> 
<div id=»droptarget»>Drop Target Zone</div> 

<p> 

<span id=»draginit-text»> 

<a href =»http :/ /www. dummies . com»>Draggable text.</a></ 
span> 

</p> 

<img id=»doorImg» alt=»Close the door» src=»door .png»/> 



<div id=»draginit-div»>Draggable div</div> 



</div> 

</body> 
</html> 

The following HTML elements will be enabled as draggable elements: drag 
init-text, draginit-div, and doorlmg. The droptarget div will be 
enabled to serve as a drop target. 
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Creating draggable elements 

Tf|e draginit-text and door Image elements are already enabled for 
drop; however, you need to prepare the draginit-div for this 
S To do so, add the following CSS rule to its style attribute: 



<div id=" draginit-div" style="-webkit-user- 

drag: element; ">Draggable div</div> 

The ondrag event is the key event that you need to account for. It is dis- 
patched when a user clicks an element and begins to drag. Given that, you're 
now ready to add ondragstart attributes to the three elements: 

<P> 

<span id=" draginit-text" ondragstart="onDragStartText 
( event ) ; " > 

<a href = "http :/ /www. dummies . com" >Draggable text.</a></ 
span> 

</p> 

<img id="doorImg" alt="Close the door" src="door .png" 

style= " -webkit-user-drag : element ; " ondragstart= 
"onDragStartlmg (event) " /> 



<div id= " draginit-div" style= " -webkit-user-drag : element ; " 

ondragstart = "onDragStartDiv (event ) " >Draggable 
div</div> 

The handler function for the draginit-text element is as follows: 

function onDragStartText ( event ) { 

// event . dataTransfer object contains info on the data 
being dragged 

// Determines the "effect" on the data being dragged - 

copied, moved, linked 
// In this case, we're flexible and will let the drag 

target decide 
event . dataTransfer . effectAllowed = "copy"; 

// Adds data in one or more formats as specified by the 

mimeType parameter 
event . dataTransfer . setData (" text/plain" , "Imagine a 

world without drag and drop. What a horrible 

world that would be . " ) ; 
event . dataTransfer . setData ( " text/uri-list " , "http : / /www. 

worldsansdraganddrop.com" ) ; 

} 
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The event . dataTransf er object is the focus of the drag-and-drop code in 
the ondrag handler. It contains the information on the data being dragged. 

set the ef f ectAllowed property to allow for copying of the data 
source to the drop target. The setData ( ) method determines the 
data and its format that you want to transfer using the drag-and-drop opera- 
tion. Instead of using the air . ClipboardOperations constants that you 
used with the Clipboard examples earlier in the chapter, you need to specify 
the format by its MIME type. (See Table 9-1 at the start of the chapter for a 
listing of the MIME types.) You can specify one or more formats, depending 
on the data you're working with. Because the span contains a link, this exam- 
ple uses both plain text and a URL list. 

Here's the ondrag handler for the draginit-div element: 

function onDragStartDiv ( event ) { 

event . dataTransf er . eff ectAllowed = "copy"; 
event . dataTransf er . setData (" text/plain" , "Divs are 
people, too ! " ) ; 

} 

The final ondrag handler is used for the doorimg element. For this example, 
I demonstrate how to use setDraglmage ( ) , which enables you to set an 
image that is displayed when the element is being dragged. The example then 
uses setData ( ) to set the image as the data to be copied: 

var draglmage = new Image ( ) ; 

draglmage . src = "plaque .png" ; 

function onDragStartlmg ( event ) { 

event . dataTransf er . eff ectAllowed = "copy"; 

event . dataTransf er . setDraglmage ( draglmage, 0, 0 ) ; 

var ddlmage = document . getElementByld ( "doorimg" ) ; 
event . dataTransf er . setData ( " image/x-vnd . adobe . air . 

bitmap" , ddlmage) ; 
var ddFile = new air . File (ddlmage . src ) ; 

event . dataTransf er . setData (" text/plain" , "Close the door 

on your way out"); 
event . dataTransf er . setData ( "application/x-vnd. adobe . air . 

file-list", new Array (ddFile) ) ; 



} 
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The example also specifies plain text and a file list as alternative formats that 
will be supported by the app for a drag-and-drop operation. 



ee drag initiator elements are now draggable either inside or 
outside the application. Figure 9-9 shows the elements of the AIR app. For 
example, if you drag the draggable text, the text and URL are displayed as 
you move your mouse (see Figure 9-10). Dropping the text into the Mac OS X 
TextEdit app inserts the text into the current file (see Figure 9-1 1). 
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Figure 9-11: 

Dropping 
the text into 
an outside 
app. 



«> O O Untitled 3 

Imagine a world without drag-and-drop. What a horrible world that would be.| 




Enabling a drop target 

For this sample application, I also want to show you how to create a drop 
target. I use the droptarget div for this great and mighty purpose. To 
enable the div as a drop target, you need to add handlers for the three drop 
target events: 

ondragenter dispatches when the mouse enters the element. 

i"* ondragover is fired continuously while mouse hovers over the 
element. 

Be careful with this event if you have an ondragenter event han- 
dler, because ondragover will quickly override changes you make in 
that handler unless you disable it with event .preventDe fault ( ) . 
Alternatively, you can simply assign the same handler to both events. 



»** ondrop is dispatched when the user lifts the mouse button to drop the 
element on the drop target. 



Here's the updated div declaration with the event attributes assigned (note 
that drag event code is bolded): 

<div id= " droptarget " ondragenter^ "onDragEnter (event) ; " 
ondragover= " onDragOver ( event ) ; " 

ondrop= "onDrop( event ) ">Dr op Target Zone</div> 
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The onDragEnter ( ) function, which follows, indicates that the div element 
will support copy drag-and-drop operations: 



on onDragEnter ( event ) { 
event . dataTransfer . dropEf feet = "copy"; 
} 

The onDragOver ( ) function disables the default ondragover event: 

function onDragOver ( event ) { 
event . preventDe fault ( ) ; 

} 

The onDrop event handler is where all the action is for the drop target. For 
demo purposes, I use getData ( ) to retrieve any text, URL, and image data: 

// Dispatched when the user lifts the mouse button to drop 

// the element on the drop target. 

function onDrop ( event ) { 

// Gets the data as specified by the specified mimeType 
var dropText = event . dataTransfer . getData (" text/plain" ) ; 
var dropUrl = event . dataTransfer . getData (" text/uri- 
list" ) ; 

var droplmg = event . dataTransfer . getData (" image/x-vnd. 

adobe. air .bitmap" ) ; 
var targetDiv = document . getElementByld (' droptarget ') ; 
targetDiv. innerHTML = "<p>Text:" + dropText + "</p>" + 
"<p>URL:" + dropUrl + "</p>"; 

if ( (event . dataTransfer . types . toString () ) . search (" image/ 
x-vnd. adobe . air .bitmap" ) > -1 ) { 
targetDiv. appendChi Id ( droplmg) ; 

} 

} 

The text and URL data is added as text inside the div using innerHTML. For 
a real application, you would obviously want to check to see whether these 
strings were null. However, I do use the types property to check whether 
bitmap data is being dragged. If its MIME type is found, the image is added as 
a child element to the div. 

Figure 9-12 shows the draggable text being dragged over the droptarget 
div. Because you specified copy as the dropEf f ect, the copy cursor is 
displayed while the mouse is on top of the div. After the text is dropped 
onto the div, the text and URL info are displayed as text (see Figure 9-13). 
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Figure 9-12: 

Dragging 
text over the 
drop target. 
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Draggable text. 



Figure 9-13: 

Dropping 
the text onto 
the div 
element. 




DragMeDropMe 
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Listing 9-4 displays the full source code for the sample app. 
-4: dragmedropme.html. 



<html> 
<head> 

<title>DragMeDropMe</ title> 

<style> 

#droptarget { 
float : right ; 

background-color: #999999; 

margin: lOpx; 

padding: lOpx; 

height: 500px; 

width: 300px; 

color: white; 

} 

#draginit-text { 
font-size: 18pt; 

} 



#draginit-div { 
width: 300px; 
height: 200px; 
text-align: center; 
color: white; 

background-color: #888888; 
border: lpt solid black; 

) 



</style> 



<script type="text/javascript" src="AIRAliases . js"x/script> 
<script type="text/javascript"> 



var drag Image; 



// Called when app loads 
function init() { 

draglmage = new Image ( ) ; 

draglmage . src = "plaque .png" ; 

} 



II ****** Drag initiator event handlers ****** 

(continued) 
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/j^i^piitched when the user begins a drag action on the text span 
If \£^3u want to disable, then you could use event .preventDef ault () ; 
function onDragStartText (event) { 

// event .dataTransfer object contains info on the data being dragged 



// Determines the "effect" on the data being dragged - copied, moved, linked 
// In this case, we're flexible and will let the drag target decide 
event .dataTransfer . effectAllowed = "copy"; 

// Adds data in one or more formats as specified by the mimeType parameter 
event .dataTransfer . setData ( "text/plain" , "Imagine a world without drag-and- 
drop . What a horrible world that would be . " ) ; 
event .dataTransfer . setData ( " text/uri-list " , "http : //www.worldsansdraganddrop . 
com" ) ; 

} 

// Dispatched when user drags the img 
function onDragStartlmg ( event ) { 

event .dataTransfer . effectAllowed = "copy"; 

// Set the drag image 

event .dataTransfer . setDraglmage ( draglmage, 0, 0 ); 
var ddlmage = document .getElementByld ( "doorlmg" ) ; 

event .dataTransfer . setData ( " image/x-vnd. adobe .air .bitmap" , ddlmage) ; 
var ddFile = new air .File (ddlmage . src) ; 

event .dataTransfer . setData ( "text/plain" , "Close the door on your way out"); 
event .dataTransfer . setData ( "application/x-vnd. adobe . air . file-list" , new 
Array (ddFile) ) ; 



} 



// Dispatched when users drag the div 
function onDragStartDiv ( event ) { 

event .dataTransfer . effectAllowed = "copy"; 

event .dataTransfer . setData ( "text/html" , "<div id=\"draginit-div\" style=\"- 
webkit-user-drag: element; \" " + 
" ondragstart= \ " onDragStartDiv ( event ) \ " >Draggable div< /div> " ) ; 
event .dataTransfer . setData ( "text/plain" , "Divs are people too!"); 



II ***** Drop target event handlers ***** 

// Dispatched when the mouse enters the element 
function onDragEnter (event) { 

// Specifies the copy effect when dropped 
event. dataTransfer. dropEf feet = "copy"; 
// event .preventDef ault ( ) ; 
} 
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// Fires continously while mouse is over the element 

Be careful if you have onDragEnter, since it will quickly 
ide changes you make in that handler. Therefore, 
a good idea to prevent default handling from taking place 
onDragOver ( event ) { 
event .preventDef ault ( ) ; 



// Dispatched when the user lifts the mouse button to drop the 
// element on the drop target, 
function onDrop ( event ) { 

si I Gets the data as specified by the specified mimeType 

var dropText = event .dataTransfer .getData ( "text/plain" ) ; 

var dropUrl = event .dataTransfer .getData ( "text/uri-list" ) ; 

var droplmg = event .dataTransfer .getData (" image/x-vnd. adobe . air .bitmap" ) ; 

var targetDiv = document .getElementByld ( 1 droptarget 1 ) ; 

targetDiv . innerHTML = "<p>Text:" + dropText + "</p>" + 
"<p>URL:" + dropUrl + "</p>"; 

if ( (event .dataTransfer . types . toString ( ) ) . search ( " image/x-vnd. adobe . air . 
bitmap") > -1 ) { 
targetDiv. appendChi Id ( droplmg) ; 

} 

} 

</script> 
</head> 

<body onload= " init ( ) " > 

<div id= " droptarget " ondragenter= " onDragEnter ( event ) ; " ondragover= " onDragOver ( ev 
ent ) ; " 

ondrop= " onDrop ( event )" >Drop Target Zone</div> 



<P> 

<span id=»draginit-text» ondragstart=»onDragStartText (event) ;»> 
<a href =»http : //www. dummies . com»>Draggable text . </ax/span> 

</p> 

<img id=»doorImg» alt=»Close the door» src=»door .png» style=»-webkit-user- 
drag : element ; » ondragstart=»onDragStart Img ( event ) »/> 



<div id=»draginit-div» style=»-webkit-user-drag: element;* ondragstart=»onDragSta 
rtDiv ( event ) »>Draggable div< /div> 

</body> 
</html> 
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Chapter 10 

Developer Freedom: 
Working with the Local 
File System 

In This Chapter 

^ Knowing how to point to files and directories 

Allowing users to browse for files 

Performing basic file operations 

Reading and writing to files 

Building a basic text editor 
•••••••••••••••••••••••••••••••••••••••••••< 




ne of the basic operations of a desktop application is the ability to read 
and write files and work with the local file system. Adobe AIR opens 



this functionality to HTML, Flex, and Flash developers. And although you can 
still access files over the Internet, the ability to work with local files gives you 
as an application developer considerable flexibility. 

In this chapter, I introduce you to how to work with files and directories in 
your application. You find out how to perform basic file operations, display 
native OS open and save dialog boxes, and read and write data to a file. I 
close out the chapter by walking you through the creation of a text editor. 



Identifying the File Classes 

When you work with native files, you work primarily with three file-related 
classes: 
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File represents a file or a directory on the local file system. You use a 
File instance for basic file operations (such as copy and delete) and 
ctory-related tasks (such as list files, create directory, and get 
ctory path). 



v>* FileStream is used for reading and writing to files. 

v* FileMode is used by FileStream to determine the permissions 
available during reading and writing operations. 

In Flex and Flash, these classes are contained in the flash . f ilesystem 
package. 



Working u/ith Files and Directories 

Whether you're working with files or directories, you use a File instance to 
point to a file or directory. As I mention previously in this chapter, the File 
object is used for basic file or directory operations. It doesn't muddy its 
hands working with the content or data of a file. The FileStream object acts 
on a File instance to do that grunt work. 



Working u/ith paths 

The File object can work with an OS-specific path or a URL to point to a 
directory or file. 



Native paths 

The nativePath property is used for getting or setting a native path. Its 
path is based on the current running OS. For example, suppose a File 
object points to a user's documents directory. On Windows, the nativePath 
would be something like C : \Documents and Settings \userName\ray 
Documents. On Mac, it would be Users \userMame\Documents. 



URLs 

The url property provides a URL-based way to point to a file. Once again, 
the formatting of the path is dependent on the current OS. For example, 
pointing to the user's documents directory, the url property would 
be something like file: ///c: /Documents%20and%20Settings/ 
userJVame/My%2 0Documents on Windows and file: ///Users/ 
userName/ Documents. 

The url property returns the path as in a URI-encoded form. As a result, 
spaces are substituted with %2 0. 
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e : / / / scheme is the standard URL scheme used for referencing 
(Yes, that's three forward slashes, not the standard two.) 



In addition to file:///, there are two additional schemes that you can use 
with the url property. These are discussed below. 



Application root directory URL 

The app : scheme points to the root directory of the application. You can 
then reference files and directories relative to this folder. For example, to 
point to an icon image in an icons subdirectory of the root folder, you can 
use app : /icons / 12 8 . png. 




Notice that the directory separators of nativePath are based on the native 
OS: \ for Windows and / for Mac. However, the url property (which is dis- 
cussed next in the "Application storage directory" section) always uses the / 
slash. 



Application storaqe directory 

The app-storage : scheme points to the application storage directory for 
your app. The application storage directory is a unique path that the AIR run- 
time automatically defines for every user of your app. You can use this loca- 
tion to store preferences, user settings, or other files. 



On Windows, the path is as follows: 



C:\Documents and Settings\useri\Jame\Application Data\ 
appl icationlD. publ i sherID\ Local Store 



Here's the path on the Mac: 



Users/ userName/ Library/ Preferences /appl i cati on ID. 
publisher ZD/Local Store 



The applicationID and publisherlD values are defined in the application 
descriptor file. The application ID is defined in the application descriptor 
file, and is typically structured like this: com. dummies . PrefManager. The 
publisher ID, on the other hand, is obtained from the certificate used to sign 
the AIR installation package. You can actually retrieve the publisher ID at 
runtime through the [air . ] NativeApplication . nativeApplication . 
publisherlD property. 

When you're testing your app before deployment, you usually don't have a 
publisher ID defined yet, so the publisherlD portion of the application storage 
path is left blank. For example, I'm working with the following path in testing 
my PrefManager app: 
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Pointing to a directory 



You can use the File object to point to several pre-defined directories, each 
of which is accessed as properties of the File object. For example, to point 
to the application directory, use the following in JavaScript: 



var dir = air . File . applicationDirectory ; 



In ActionScript, you use: 



private var dir: File = File . applicationDirectory; 



You can then access a subdirectory or file by using the resolvePath ( ) 
method. For example, to point to an assets subdirectory: 



dir = dir . resolvePath ( "assets ") ; 



If you want to access a nested subdirectory, be sure to use a forward slash. 
For example: 

dir = dir . resolvePath ( "assets/ess ") ; 

You can also use a shortcut syntax to put all the code in one line. Here's the 
JavaScript version: 

var dir = air . File . applicationDirectory . 
resolvePath( "assets/ess" ) ; 

You can use the File object to point to several other predefined directories 
that are shown in Table 10-1. 



Table 10-1 


Predefined File System Directories 


Directory 


File Object Windows Path Mac OS X Path 




Property/ 




Method 


Application 


[air . ] File . 


directory 


application 




Directory 
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Directory 


File Object 


Windows Path 


Mac OS X Path 




Property/ 








)ks 


Method 








Application 


[air . ] File . 


C:\ 


Users/user 


storage 


application 


Documents 


Name /Library/ 




Storage 


and 


Preferences/ 




Directory 


Settings\ 


appli cationID . 






userName\ 


publisherlD/ 






Application 


T.nrfll Strcre 






DataXappli 








cationID . 










publish 










prTfl\ T .i-ir 1 3 1 










o LUI c: 






User's 


[air . ] File . 


C: \ 


Users / userName 


home 


user 


Documents 






directory 


Directory 


and 










SettingsX 










liocl ivciiiicr 






User's 


[air . ] File . 


C:\ 


Users / userName/ 


document 


documents 


Documents 


Documen 


ts 


directory 


Directory 


and 










Settings\ 










userName \My 
















User's 


[air . ] File . 


C: \ 


Users / userName/ 


desktop 


desktop 


Documents 


Desktop 




dirprtnrv 

tin (ju lu i y 




cincl 










C q -1- H — i fn c" \ 

Oct i — Liiy o \ 










7 7 qp Tj\J^TTIf^ \ 
Ci 1^ -L. ivdin^ \ 










ripc'lcl'n'n 






File system 


[air . ] File . 


Returns c : and 


Returns the / root 


root 


getRootDir 


all other root 


directory 






ectories ( ) 


volumes 






Temporary 


[air . ] File . 


C:\ 


/private /var/ 


directory 


create 


Documents 


tmp/ folders . 




TempDirec 


and 


501 /Temporary 




tory ( ) ; 


Settings\ 


Items/ temp 






rich\Local 


DirName 








Settings\ 










Temp\ temp 










DirName 
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In addition to the predefined directories, you can access any arbitrary direc- 
tory on the file system through the [air . ] File . nativePath property. For 
to access a c : \Air directory on a Windows machine in JavaScript: 



ir = new air. FileO; 
dir .nativePath = "C:\\Air\"; 

You can use the url property as well. Here's an ActionScript example on a 
Mac: 

var dir: File = new FileO; 

var urlString : String = " f ile : / / /Users/rich/Books " ; 
dir. url = urlString; 



Pointing to a file 

Big surprise, but the File object also is used to point to specific files. 



Using the resolvePath ( ) method, you can point to a specific file. Here's a 
JavaScript example, pointing to a pref s . xml file in the application storage 
directory: 



var pref File = File . applicationStorageDirectory; 
pref File = pref File . resolvePath ( "pref s . xml ") ; 




Or, in ActionScript: 












public var pref File : File 




= File. 





applicationStorageDirectory ; 
pref File = pref File . resolvePath ( "pref s . xml ") ; 

You can also use the nativePath and url properties to point to a specific 
file. Here's a JavaScript example for a Windows machine: 

var myFile = new air. FileO; 

myFile. nativePath = "C: \\AirWtext.txt" ; 

Here's a second JavaScript example using the url property, which is prefer- 
able for working across operating systems: 

var myFile = new air. FileO; 
myUrl = " file :// /C : /Air/text . txt " ; 
myFile. url = myUrl; 
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As a shortcut, you can also pass a path as a parameter to the File ( ) con- 
structor function. The following ActionScript example uses both a Windows 
th and URL string: 



var filel:File = new File ( "C" \\Books\\duittmies_toc . txt" ) ; 
var file2Path: String = " f ile : / / /C : /Books/dummies_toc2 . 
txt " ) ; 

var file2:File = new File ( f ile2Path) ; 



AiioWinq Users to Brortse 
For a Directory and Files 



The File object builds in the functionality to allow users to browse and 
select a directory, file, or set of files using native OS dialog boxes. 



Displaying a Choose Directory dialog box 

If you'd like to allow users to browse and pick a directory from inside your 
application, use the File .browseForDirectory ( ) method. When you use 
this method in conjunction with an Event . select event handler, you can 
capture the directory selected by the user and do something with it. 

For example, the following JavaScript snippet displays a Select Directory 
dialog box. The user then selects the desired directory and clicks OK (or 
Choose). The directory selected is automatically saved in the nativePath 
and url properties. The selectDirectory ( ) event handler then does 
something with the user's path. Here's the code: 

var folder = air. File. userDirectory; 

function showDirBrowser ( ) { 

folder . addEventListener ( air . Event . SELECT, 

selectDirectory) ; 
f older. browseForDirectory ( "Select your coolest folder"); 

} 

function selectDirectory (evt) { 

var userDreamFolder = folder . nativePath; 

// do something cool here with that cool folder 

} 
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Or, in ActionScript: 

var folder:File = File . userDirectory ; 



c function showDirBrowser ( ) :void { 
folder . addEventListener (Event . SELECT, selectDirectory) ; 
folder .browseForDirectory ( "Select your coolest folder") 

} 

public function selectDirectory (evt : Event) : void { 
var userDreamFolder : String = folder . nativePath; 
// do something cool here with that cool folder 

} 

Figures 10-1 and 10-2 show the dialog box displayed on Windows and Mac, 
respectively. 



Browse For Folder 
Select your coolest folder 



Figure 10-1: 

The Select 
Directory 
dialog box in 
Windows. 



Desktop 



l-j ihty Documents j 
j My Computer 
*.j My Network Places 
; Q My Extra Junk 
Q ones i like 



Make New Folder 



Displaying a File Open and 
File SaVe dialog box 

The ubiquitous File Open dialog box can be displayed using the File . 
browseForOpen ( ) method. Its functionality is quite similar to File . 
browseForDirectory ( ) , except you can also define an optional file filter 
array to specify the types of files you'd like to allow to be selected and opened. 
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Select your coolest folder 




Figure 10-2: 

The Select 
Directory 
dialog box 
in Mac. 



Drop Box 

B 

wallpaper 



Cancel ) ( Select "l 



You define a listener to Event . select to do something with the file after 
the user has selected it. Here's sample JavaScript code: 

var file = air . File . documentsDirectory; 

function fileOpen() { 

var filter : FileFilter = new air. FileFilter ( "Documents" , 

" * . txt ; * . html ; * . pdf ; * . doc ; " ) ; 
f ile . addEventListener (air . Event . SELECT, 

f ileOpenHandler ) ; 
f ile. brows eForOpen ( "Select your most awesomest file", 

[filter] ) ; 

} 

function f ileOpenHandler (evt) { 
var openedFile = f ile . nativePath; 
/ / do something . anything . 

} 

Or, if you prefer ActionScript, use: 

public var file: File = File . documentsDirectory; 

public function f ileOpen ( ) : void { 

var filter : FileFilter = new FileFilter ( "Documents" , 

" * . txt ; * . html ; * . pdf ; * . doc ; " ) ; 
file . addEventListener (Event . SELECT, f ileOpenHandler ) ; 
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file .browseForOpen (" Select your most awesomest file", 
[filter] ) ; 



public function fileOpenHandler (evt : Event ) :void { 
var openedFile : String = file . nativePath; 

} 



Figure 10-3 shows the dialog box in Windows. 



Figure 10-3: 

File Open 
dialog box in 
Windows. 



Select your most awesomest file 
Look in: | C3 whythebike 



MyRecert 
Documents 



"3 *= cs ef H* 



is 

My Computer 



iL_^images| 

._book.html 

,_index.html 

._schedule.html 

._sponsors.html 

._team.html 

,_tour colors.txt 

._whythebike.html 
]§} book.html 

_ expman_tour_route_official.pdf 

*j index.html 

m schedule.html 

i#J sponsors.html 

i«) team, html 

W\ tour colors.txt 



^whythebike-html 



File name: 
Files of type: 



r 



[ Documents 



You can also use the File . browseForSave ( ) method to display a File Save 
dialog box. It works the same basic way, although no FileFilter parameter 
is available for this method. Here's a JavaScript snippet: 

var file = air . File . documentsDirectory; 

function f ileSave ( ) { 

f ile . addEventListener (air . Event . SELECT, 

f ileSaveHandler ) ; 
f ile. browseForOpen ( "Save your most precious file now! Or 

else ..." ) ; 

} 



function f ileSaveHandler (evt) { 
var savedFile = file .nativePath; 

// I will do something with this var now. Really! 

} 
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You may have occasion to allow the user to select multiple files from a dialog 
box for processing. Rather than call File .browseForOpen ( ) multiple 
times, the friendlier option is to use File .browseForOpenMultiple ( ) . 
This method allows users to select multiple files in the dialog box and returns 
the selection as an array of filenames. 

As with browseForOpen ( ) , you can specify an optional [air . ] 
FileFilter instance to define the types of files you'd like to allow to be 
selected and opened. 

The following JavaScript code attaches an event listener to air . 
FileListEvent . select_multiple and then displays the Select Multiple 
Files dialog box. When the user selects one or more files, f ileOpenList- 
Handler ( ) is called. Here's the code: 

var file = air . File . documentsDirectory ; 

function f ileOpenFileList ( ) { 

file . addEventListener (air . FileListEvent . SELECT_MULTIPLE, 

f ileOpenListHandler ) ; 
file .browseForOpenMultiple ( "Select your most awesomest 

files" ) ; 

} 



function f ileOpenListHandler (evt) { 
var str = " " ; 

for (var i=0 ; i<evt . files . length; i++) { 
str += evt . files [ i ]. nativePath + "\n"; 

} 

alert (str) ; 



The ActionScript code that follows performs the same basic process, except 
that the files selected are assigned to the text property of an mx : Text Area 
element: 



public var file: File = File . documentsDirectory ,- 

public function f ileOpenFileList (): void { 

file . addEventListener (FileListEvent . SELECT_MULTIPLE , 

f ileOpenListHandler ) ; 
file .browseForOpenMultiple (" Select your most awesomest 

files" ) ; 



Part III: Programming the Adobe AIR API 



DBooks 

var 



function f ileOpenListHandler ( evt : FileListEvent ) :vo 

id { 

var str: String = ""; 
for (var i:uint =0; i < evt . files . length; i++) { 
str += evt . files [ i ]. nativePath + "\n"; 

} 

taFavoriteList . text = str; 



} 



Figure 10-4 shows the mx : Text Area control that displays filenames returned 
from browseForOpenMultiple ( ) . 



Favorite Folder: 
Favorite file; 
Favorite List: 



/users/rich/Development/aircev/HTML/AIRMenusMTML/* 
/users/nch/Development/alrdev/HTMLyAIRMenusMTML/* 
/users/rich/ Development/airdev/HTML/AJRMenusMTML/* 
/users/rich/ Development/alroev/HTMLyWRMenusHTML/* 



Figure 10-4: 

Selected 
files are 
displayed in 
the text area 
control. 



File Operations > 



Listing 10-1 provides the Flex source code of a sample app that illustrates 

how to use browseForDirectory ( ) , browseForOpen ( ) , and browse- 
ForOpenMultiple ( ) . The user selection for a dialog box is displayed in a 
corresponding text control. 



Listing 10-1: Filer.mxml 

<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 

<mx : WindowedApplication xmlns :mx= "http : / /www. adobe . 

com/2 006/mxml" layout=" absolute" height="332" 
width="540" alpha="0 . 67 "> 
<mx : Script> 
<! [ CDATA [ 

public var folder: File = File . userDirectory; 
public var file: File = File . documentsDirectory; 

public function showDirBrowser ( ) :void { 
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folder = new File ( ) ; 

folder . addEventListener (Event . SELECT, 

selectDirectory) ; 
folder .browseForDirectory ( "Select your coolest 
folder" ) ; 
} 

public function selectDirectory (evt : Event) : void { 
tiFavoriteFolder . text = folder . nativePath; 

} 

public function f ileOpen ( ) : void { 

var filter : FileFilter = new FileFilter (" Documents " , 

" * . txt ; * . html ; * . pdf ; * . doc ; " ) ; 
file . addEventListener (Event . SELECT, 

f ileOpenHandler ) ; 
file . browseForOpen (" Select your most awesomest 

file", [filter] ) ; 

} 

public function f ileOpenHandler (evt : Event) : void { 
tiFavoriteFile . text = file . nativePath; 

} 

public function f ileOpenFileList ( ) : void { 

file . addEventListener (FileListEvent . SELECT_MULTIPLE, 

f ileOpenListHandler ) ; 
file.browseForOpenMultiple ( "Select your most 
awesomest files"); 

} 

public function f ileOpenListHandler (evt : FileListEvent) 
:void { 
var str: String = ""; 

for (var i:uint =0; i < evt . files . length; i++) { 
str += evt . files [ i ]. nativePath + "\n"; 

} 

taFavoriteList . text = str; 

} 

] ]> 

</mx: Script> 

<mx:Form x="10" y="10" width="464" height= " 2 84 " > 
<mx:FormItem label= " Favorite Folder: "> 

<mx:TextInput width="32 0" id= " tiFavoriteFolder " 
editable=" false" enabled="true" /> 
</mx : FormItem> 

<mx:FormItem label= " Favorite File:"> 

<mx:TextInput width="32 0" id= " tiFavoriteFile " 
editable=" false" enabled="true" /> 
</mx : FormItem> 

<mx:FormItem label=" Favorite List:"> 
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<mx:TextArea id= " taFavoriteList " width="32 0" 

height="187" wordWrap=" false" editable=" false" 
enabled= " true " / > 
</mx : FormItem> 
</mx: Form> 

<mx:Button x="477" y="56" label="..." width="37" 

id="btnOpenFile" click= " f ileOpen ( ) "/> 
<mx : Button x=" 477" y="82" label="..." 

width= " 37 " id= "btnOpenFileList " 

click= " f ileOpenFileList ( ) "/> 
<mx:Button label=" . . . " width="37" id= "btnSelectFolder " 

click= " showDirBrowser ( ) " x="477" y="28"/> 
</mx : WindowedApplication> 



Performing Directory and File Operations 

There are several file utility functions that you can perform inside your 
Adobe AIR application using the File object. You can use these when you 
need, for example, to create a directory, create a temporary file or directory, 
or copy a file. 



Creating a directory 

When you want to create a new directory, use the resolvePath ( ) method 
to navigate to the location in which you want the directory to be; then, 
follow that up with a call to File . createDirectory ( ) . The File . create 
Directory ( ) method first checks to see whether that directory already 
exists. If not, then it creates the directory. The following code snippet creates 
a wallpaper subdirectory inside the desktop folder. Here's the JavaScript: 

var folder= air .File. desktopDirectory . 

resolvePath ( "wallpaper" ) ,- 
folder . createDirectory ( ) ; 

Or, in ActionScript: 



var folder: File = File . desktopDirectory . 

resolvePath ( "wallpaper" ) ; 
folder . createDirectory ( ) ; 
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Creating a temporary directory or file 



mon need, when you're working with local files and storage, to have 
ary place to store some data. Rather than come up with your own 
routine to identify and create a unique directory name, you can use File . 
createTempDirectory ( ) . This method creates a unique folder inside the 
main temporary directory of the operating system. For JavaScript, you use: 



var tmp = air . File . createTempDirectory () ; 



ActionScript looks like this: 

var tmp:File = File . createTempDirectory () ; 




What's more, if you want to create a temporary file, you can use the File . 
createTempFile ( ) method. When called, AIR returns a pointer to a 
uniquely named temporary file in the temporary directory of the OS. For 



example: 








var tmpFile = air. File 
alert (tmpFile. name) ; 


. createTempFil 


e() ; 




AIR does not remove the directory automatically when your app closes. 



Therefore, be sure to add a clean-up routine to execute when the app closes to 
remove any temporary directories and files that you create. 



Copying and moving directories and files 

You can synchronously copy a file or the entire contents of one directory 
to another using the File . copyTo ( ) method. Consider the following 
JavaScript example to see how this works for directories: 

var sourceFolder = air. File. desktopDirectory.resolvePath( "wallpaper" ) ; 

var targetFolder = air. File. desktopDirectory.resolvePath( "son of wallpaper"); 

sourceFolder . copyTo (targetFolder) ; 



In this code, the wallpaper directory is copied to a new directory named 
son of wallpaper directory inside of the system's desktop folder. 



By default, if the target directory already exists, the operation will fail. 
However, the copyTo ( ) method contains an optional overwrite parameter 
that, if true, will first delete the target directory first and create a new one for 
this usage. 
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ceFolder:File = File .desktopDirectory . resolvePath ( "wallpaper" ) ; 
etFolder:File = File. desktopDirectory. resolvePath ("son of wallpaper"); 



sourceFolder . copyTo (targetFolder, true) ; 

If you'd prefer to move the directory to a different location rather than 
copy its contents, use File .moveTo ( ) . It takes the same parameters as 
copyTo ( ) but performs a move routine rather than a copy. 

Files are synchronously copied and moved in the exact same way. The follow- 
ing JavaScript code copies textl . txt to a new file named text2 . txt: 

var sourceFile = air .File .desktopDirectory . resolvePath ( "wallpaper/textl . txt ") ; 
var targetFile = air. File. desktopDirectory. resolvePath ( "wallpaper/text2 .txt" ) ; 
sourceFile. copyTo (targetFile) ; 

Both of these methods also have asynchronous versions — copyToAsync ( ) 
and moveToAsync ( ) — when you prefer to perform these operations asyn- 
chronously. After these operations are completed, they dispatch a complete 
Event (or an ioError event if the operation failed). You can add event lis- 
teners to these events for processing after the operation completes or fails. 
Here's an example of copying a directory asynchronously. First, for HTML 
developers, here is the JavaScript: 

function createBackupCopy ( ) { 

var sourceFolder = air . File . applicationDirectory. 

resolvePath ( "Data" ) ; 
var targetFolder = air . File . applicationDirectory . 

resolvePath ( "Data_backup_l " ) ; 

sourceFolder . addEventListener (air . Event . COMPLETE, 

onCopyComplete) ; 
sourceFolder . addEventListener ( air . IOErrorEvent . IO_ERROR, 

onCopyError) ; 
sourceFolder . copyToAsync (targetFolder) ; 

} 

function onCopyComplete (evt) { 

alert ("Wow, our backup operation actually worked. Is 
that cool or what?"); 

} 



function onCopyError (evt) { 

alert (" Something really, really bad just happened."); 

} 
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And, for Flex and Flash developers, here's the ActionScript: 

port mx . controls . Alert ; 



public function createBackupCopy ( ) :void { 

var sourceFolder : File = File . applicationDirectory . 

resolvePath( "Data" ) ; 
var targetFolder : File = File . applicationDirectory . 
resolvePath ( "Data_backup_01 " ) ; 



sourceFolder . addEventListener ( Event . COMPLETE , 

onCopyComplete) ; 
sourceFolder . addEventListener ( IOErrorEvent . 

IO_ERROR, onCopyError) ; 
sourceFolder . copyToAsync ( targetFolder) ; 



public function onCopyComplete (evt : Event ): void { 
Alert . show ( "Wow, our backup operation actually 
worked. Is that cool or what?"); 

} 

public function onCopyError (evt : IOErrorEvent ) :void { 
Alert . show (" Something really, really bad just 
happened . " ) ; 



Deleting and moVinq to trash 

If you want to delete a file or directory or else just move it to the trash (recy- 
cle bin), use one of the following methods: 

V* File. moveToTrash ( ) 

File . moveToTrashAsync ( ) 

File . deleteFile ( ) 
I"* File . deleteFileAsync ( ) 

The following snippet sends a file to the trash: 

var doomedFile = air . File . applicationStorageDirectory. 

resolvePath ( "pref . xml " ) ; 
doomedFile .moveToTrash ( ) ; 



If you're using the asynchronous versions of these methods, you can assign a 
handler to the complete event when the process has been finished. 
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Reading and Writing to Files 
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point to a file using the File object, you probably want to do 
something with it, such as adding or saving data inside it. That's where the 
FileStream object comes in. It takes a File instance you've already initial- 
ized and allows you to read from or write to it. 

Whether you read or write to a file stream, you first need to open it using 
either the open ( ) or openAsync ( ) method: 



fileStream . open ( file , fileMode) ; 
fileStream. openAsync (file, fileMode) ; 




Both methods have a fileMode parameter that specifies the capabilities of 
the FileStream object. There are four possible file modes: 

i>* [air. ] FileMode .read specifies that the file is open for reading only. 

[air . ] FileMode .write indicates that the file is open for writing. If 
the file already exists on the system, the existing contents are deleted. 
(Use FileMode .append if you don't want to overwrite the contents.) If 
the file does not exist, it is created. 

V [air . ] FileMode .append tells AIR that the file is open in "append 
mode," meaning that new data is added to the end of the file instead of 
replacing existing data. If the file does not exist, the file is created. 

[air . ] FileMode .update specifies that the file is open for both read- 
ing and writing. Use this mode when you need random read/write access 
to the file. When a file is being written to, only the bytes at the current 
location are overwritten. As you might expect by now, if the file doesn't 
exist, it is created. 

After you've opened a file, you're reading for the two R's — reading and 'riting. 
(Okay, it's technically an R and a W, but two R's has a better ring to it.) 

If you'd like to see how to asynchronously read/write to a file, skip over to the 
"AIRWrite: Creating a Simple Text Editor" section, later in this chapter. 



Read from a file 

You can use several read methods for reading data from a file stream. For 
general-purpose use with text files, you'll often want to use readMulti- 
Byte ( ) or readUTFBytes ( ) . The readMultiByte ( ) method reads a 
mutibyte string from the file stream using a character set you specify. The 
readUTFBytes ( ) method reads data into a string using the UTF-8 character 
set. (See the "AIRWrite: Creating a Simple Text Editor" section, later in this 
chapter, for examples of this method.) 
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To read a file and assign the data to a variable using readMultiByte ( ) , you 
use the following JavaScript code: 



le = air . File . desktopDirectory; 
= f ile . resolvePath ( " textl . txt " ) ; 
var fs = new air . FileStream () ; 
f s . open ( file, air . FileMode . READ) ; 
var str = fs . readMultiByte ( file . size, air. File. 

systemCharset ) ; 
// do something with str 
f s . close ( ) ; 



Here's the ActionScript version: 



var file: File = File . desktopDirectory; 
file = file . resolvePath (" textl . txt ") ; 
var fs : FileStream = new FileStream () ; 
f s . open ( file, FileMode . READ) ; 

var str:String = fs . readMultiByte ( file . size , File. 

systemCharset) ; 
// do something with str 
f s . close ( ) ; 

The open ( ) method opens the file instance for reading. The second file- 
Mode parameter is used to specify the capabilities of the FileStream object. 
Using FileMode .read enables the FileStream instance to read from the 



The readMultiByte ( ) method reads a multibyte string from the file stream 
using the character set specified by File . systemCharset and returns it as 
a string. The size of the file stream is indicated by the file. size property. 

When you're done reading, call the close ( ) of the FileStream instance to 
close the file stream. 




There are also additional reading methods, including readBytes ( ) (for 
assigning to a ByteArray) and the lesser used readUTF ( ) (for files that 
have the length of the file's text data precede the data itself). 



Write to a file 

The write methods used to write to a file stream parallel the read methods. 
To write to a file using writeMultiByte ( ) , here's the JavaScript code: 

var file = air . File . desktopDirectory ; 
file = file . resolvePath (" textl . txt ") ; 
var fs = new air . FileStream () ; 
f s . open ( file, air .FileMode. WRITE) ; 
var str = "This is amazing!" 
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f s . writeMultiByte ( str , air . File . systemCharset) ; 




var file:File= File . desktopDirectory; 

file = f ile . resolvePath ( " textl . txt " ) ; 

var f s : FileStream = new FileStream () ; 

f s . open ( file, FileMode .WRITE) ; 

var str:String = "This is amazing!" 

fs .writeMultiByte (str , File . systemCharset) ; 

f s . close ( ) ; 

Check out the following section to discover more techniques related to writ- 
ing to a file stream. 



AlKU/rite: Creating a Simple Text Editor 

Building a text editor is perhaps the best way to demonstrate the basic read 
and write capabilities of Adobe AIR. You can then visually see how the read 
and write operations work inside your own app. 

In this part of the chapter, I create both an HTML and Flex version of the 
editor and walk you through the code of the HTML version. Both versions 
offer essentially the same functionality. 



HTML Vevsion 

The following sections walk you through the construction of the AIRWrite 
text editor. 



Build the Ul 

You begin by defining a very simplistic UI — just a single textarea element: 
<p>< textarea id= " TextEdi tor " >< / textareax /p> 



For this example, make the textarea fill the contents of the window and be 
in monospaced font by adding the following style: 



#TextEditor { 




width: 100%, • 




height : 100%; 




font-family: "Courier New" 


Courier, monospace; 


font-size : 14px; 

} 
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That's all the UI design you need to do for this app, so you're ready to move 
on to the JavaScript coding. 

AlRAtiases.js file 

Before adding the app specific code, you first need to add the AiRAliases . 
j s file, as follows: 



<script type="text/javascript" src= "AiRAliases . js"x/script> 



Add a root menu 

Keeping the UI minimal, you can have the users control the file open and save 
processes through a top-level menu. Add four menu items: New, Open, Save, 
and Exit/Quit. (See Chapter 8 for the full scoop on working with menus.) 

In an init ( ) function that executes when the app is loaded (by calling 

window. addEventListener (" load" , init, f alse) , you create the 
NativeMenu object that serves as the root menu: 



var rootMenu = new air .NativeMenu () ; 
rootMenu . addSubmenu ( createFileMenu ( ) , "File") ; 



// Mac 

if (air .NativeApplication. supportsMenu) { 

air .NativeApplication.nativeApplication. menu = rootMenu; 

} 

/ / Windows 

if ( air . NativeWindow . supportsMenu ) { 
window . nativeWindow. menu = rootMenu; 

} 



The createFileMenu ( ) called by the rootMenu . addSubmenu ( ) line is 
defined as follows: 



/ * * 

* Creates the File menu for app 

*/ 

function createFileMenu ( ) { 

var mnu = new air . NativeMenu () ; 
createMenuCommand ( mnu, 'New', 'n', null, 0, 
f ileNew) ; 

createMenuCommand ( mnu, 'Open', 'o', null, 0, 

f ileOpen) ; 
createMenuSeparator (mnu) ; 

createMenuCommand ( mnu, 'Save', 's', null, 0, 

f ileSave) ; 
createMenuSeparator (mnu) ; 
//If Mac OS X, then use Quit label 
if (air .NativeApplication. supportsMenu) { 

createMenuCommand ( mnu, 'Quit', 'q', null, 0, 

fileExit) ; 
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} 

// If Windows, then use Exit 
lse { 

createMenuCommand ( nmu, 'Exit', 'x', null, 0, 
fileExit) ; 
} 

return mnu; 

} 



The createMenuCommand ( ) and createMenuSeparator ( ) functions are 
helper routines that create a menu command or separator based on the sup- 
plied parameters. (These are shown in Listing 10-2, which appears a little 
later.) 



Opening a (He asynchronously 

When the Open menu item is selected, the following routine is called: 

function f ileOpen (evt) { 

file. addEventListener (air. Event. SELECT, onFileSelect ) ; 
f ile . brows eForOpen ( "Open" ) ; 

} 



The addEventListener ( ) method attaches onFileSelect ( ) as a han- 
dler to process the file that is selected from the dialog box displayed using 

browseForOpen ( ) . 

The onFileSelect function calls openAsync ( ) to open the file asynchro- 
nously. When using openAsynch ( ) , you need to define handlers to trigger 
when the reading process has finished or when an error has occurred. Here's 
the code: 



function onFileSelect (evt) { 
var fs = new air . FileStream ( ) ; 
f s . openAsync ( file , air . FileMode . READ) ; 
fs . addEventListener (air . Event .COMPLETE, onFileRead) ; 
f s . addEventListener (air . IOErrorEvent . IO_ERROR, 

onlOReadError ) ; 
isDirty = false; 
isNewFile = false; 

document . title = "AIRWrite - " + file. name; 



The isDirty variable is used to determine whether a file has been modified 
by the user. The isNewFile variable is used to determine whether a file has 
ever been saved before. 



For asynchronous reads, you want to place the file stream reading code 
inside the complete event handler: 
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function onFileRead ( evt ) { 

var fs = air . FileStream ( evt . target ) ; 

str = f s . readUTFBytes (f s . bytesAvailable) ; 
ment . getElementByld (" TextEditor "). value = str; 
lose ( ) ; 
} 



In this function, the readUTFBytes ( ) routine assigns the contents of the file 
to the str variable. This value is then set as the value for the textarea 
element. 



In case something goes wrong during the file open process, here's a handler 
to deal with it: 



function onlOReadError (evt) { 

alert (" Something wacky happened. We are unable to open 
+ f ile . nativePath) ; 

} 



Sai/ing a (He asynchronously 

The Save menu item calls the f ileSave ( ) function: 



function f ileSave ( evt ) { 
if UisNewFile) { 

var fs = new air . FileStream () ; 

f s . openAsync ( file , air . FileMode .WRITE) ; 

f s . addEventListener (air . IOErrorEvent . IO_ERROR, 

onlOWriteError ) ; 
var str = document . getElementByld 

( "TextEditor " ) .value; 
str = str . replace (/ \n/g, air . File . lineEnding) ; 
f s . writeUTFBytes (str) ; 
f s . close ( ) ; 
isDirty = false; 

} 

else { 

f ileSaveAs (evt) ; 

} 

} 



For files that have been previously saved, a file stream is opened for writ- 
ing using openAsync ( ) . The content of the textarea is then assigned to 
the str variable. Before writing this string to the file, you replace the new 
line characters (\n) with a platform specific line ending character (the air 
File . lineEnding property). The file stream is written using writeUTF- 
Bytes ( ) and then closed. 
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For new files, the f ileSaveAs ( ) function is called, as follows: 

r*N 1^ ^ ^ I jitfftion fileSaveAs (evt) { 

I I II M III J| J l\ Sale. addEventListener (air .Event . SELECT, 

onFileSaveAsSelect) ; 
file .browseForSave (" Save As") ; 

} 

This function calls the Save dialog box and sets the handler for the file selec- 
tion process to onFileSaveAsSelect ( ) , as follows: 

function onFileSaveAsSelect (evt) { 

document . title = "AIRWrite - " + file. name; 
isNewFile = false; 
f ileSave (evt) ; 

} 

By the time this routine nears completion, the file will have a name and be 
read for saving. As a result, the f ileSave ( ) function is called again. 

Listing 10-2: AIRWriteHtml.html 

<html> 
<head> 

<title>AIRWriteHtml</title> 
<style type= " text/ess " > 
#TextEditor { 

width: 100%, • 

height: 100%; 

font-family: "Courier New", Courier, monospace; 
font-size : 14px; 

} 

</style> 

<script type=" text /javascript" src= "AIRAliases . j s " ></ 
script> 

<script type= "text/ javascript "> 
var file; 

var isDirty= false; 
var isNewFile = false; 

window. addEventListener (" load" , init, false); 



* Initializes the app after loading 
* 

*/ 

function init ( ) { 

file = new air.Filef); 

var rootMenu = new air .NativeMenu ( ) ; 
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/ Mac 

(air .NativeApplication. supportsMenu) { 
air . NativeApplication . nativeApplication . menu 
rootMenu ; 

} 

/ / Windows 

if (air .NativeWindow. supportsMenu ) { 

window . nativeWindow. menu = rootMenu; 

} 



// Start out with a blank doc 
f ileNew(null) ; 

} 



* Creates new blank file 

*/ 

function fileNew(evt) { 

file = air . File . desktopDirectory; 

file = file.resolvePathCUntitled.txt"); 

isDirty = false; 

isNewFile = true; 

document . getElementByld ( "TextEditor" ) .value = ""; 
document . title = "AIRWrite - " + file.name; 

} 

* Displays File Open dialog box 
*/ 

function f ileOpen ( evt ) { 

file. addEventListener (air. Event. SELECT, onFileSelect) ; 
f ile . brows eForOpen ( "Open" ) ; 

} 

/ * * 

* Opens selected file for editing 

*/ 

function onFileSelect (evt) { 
var fs = new air . FileStream ( ) ; 
f s . openAsync ( f ile , air . FileMode . READ) ; 
fs . addEventListener (air . Event .COMPLETE, onFileRead) ; 
f s . addEventListener (air . IOErrorEvent . IO_ERROR, 

onlOReadError ) ; 
isDirty = false; 
isNewFile = false; 

document . title = "AIRWrite - " + file.name; 

} 



/ * * 

* Handler for reading file 



(continued) 
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tion onFileRead (evt) { 

fs = air . FileStream ( evt . target ) ; 
var str = f s . readUTFBytes ( f s . bytesAvailable) ; 
document . getElementByld (" TextEditor ")■ value = str; 



* Write file to disc 

*/ 

function f ileSave ( evt ) { 
if ( ! isNewFile) { 

var fs = new air . FileStream () ; 

fs . openAsync (file, air . FileMode .WRITE) ; 

f s . addEventListener (air . IOErrorEvent . IO_ERROR, 

onlOWriteError ) ; 
var str = document . getElementByld (" TextEditor " ) . 
value ; 

str = str . replace (/ \r/g, "\n"); 

str = str. replace (An/g, air . File . lineEnding) ; 

f s . writeUTFBytes (str) ; 

f s . close ( ) ; 

isDirty = false; 

} 

else { 

f ileSaveAs (evt) ; 

} 

} 

I * * 

* Displays File Save dialog box 

*/ 

function f ileSaveAs ( evt ) { 

f ile . addEventListener (air . Event . SELECT, 

onFileSaveAsSelect) ; 
f ile. browseForSave ( "Save As") ; 

} 

* Calls FileSave based on dialog box selection 

*/ 

function onFileSaveAsSelect (evt) { 

document . title = "AIRWrite - " + f ile. name; 
isNewFile = false; 
f ileSave (evt) ; 

} 

I * * 

* Exit the app 

*/ 

function f ileExit (evt) { 

air .NativeApplication.nativeApplication. exit ( ) ; 



Chapter 10: A New Developer Freedom: Working with the Local File System 



ooks 



_ ror handlers 

'/ 

function onlOReadError (evt) { 

alert (" Something wacky happened. We are unable to open 
" + f ile . nativePath) ; 

} 



function onlOWriteError ( evt ) { 

alert ( "We are really sorry, but the file cannot be 
saved. It's not our fault .. .really !") ; 

} 



* Creates the File menu for app 

*/ 

function createFileMenu ( ) { 

var mnu = new air . NativeMenu ( ) ; 
createMenuCommand ( mnu, 'New', 'n', null, 0, 
f ileNew) ; 

createMenuCommand ( mnu, 'Open', 'o', null, 0, 

f ileOpen) ; 
createMenuSeparator (mnu) ; 

createMenuCommand ( mnu, 'Save', 's', null, 0, 

f ileSave) ; 
createMenuSeparator (mnu) ; 
//If Mac OS X, then use Quit label 
if (air .NativeApplication. supportsMenu) { 

createMenuCommand ( mnu, 'Quit', 'q', null, 0, 

fileExit) ; 

} 

// If Windows, then use Exit 
else { 

createMenuCommand ( mnu, 'Exit', 'x', null, 0, 
fileExit) ; 

} 

return mnu; 



/ * * 

* Creates a "fully loaded" menu command based on 
parameters 

* 

*/ 

function createMenuCommand (menuContainer , itemLabel, 
itemKey, itemModif iers , itemMnemonic , 
selectHandler ) { 

var cmd = air .NativeMenu (menuContainer ) .addltem(new 
air . NativeMenuItem ( itemLabel ) ) ; 

cmd.mnemoniclndex = itemMnemonic; 

(continued) 
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cmd . keyEquivalent = itemKey; 
( itemModif iers != null ) { 
cmd . keyEquivalentModif iers = itemModif iers ; 

} 



if (selectHandler != null ) { 

cmd. addEventListener (air . Event . SELECT, 
selectHandler) ; 

} 

return cmd; 

} 



/ * * 

* Creates a menu separator 

*/ 

function createMenuSeparator (menuContainer ) { 

var sep = air .NativeMenu (menuContainer ) .addltem(new 

air .NativeMenuItem ( " sep" , true) ) ; 
return sep; 

} 



</script> 
</head> 

<body> 

<p>< textarea id= " TextEdi tor " >< / textareax /p> 

</body> 

</html> 



Ftex Version 

The Flex version of the AIRWrite editor is shown in Listing 10-3. 



Listing 10-3: AIRWrite.html 

<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 

<mx : WindowedApplication xmlns :mx= "http : / /www. adobe . 

com/2 006 /mxml" layout= " absolute " width="764" 

height="454" 

applicationComplete= " init ( ) " styleName="sansChrome" 
backgroundGradientAlphas= "[0.3, 0 . 3 ] " > 

<mx: Style> 

. sansChrome { background-color : " " ; } 
</mx : Style> 
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Script> 
[CDATA [ 



import mx . controls .Alert ; 
import flash . display . NativeMenu ; 

import flash . display .NativeMenuItem; 
import mx . events . * ; 



private var file: File; 

public var isDirty: Boolean = false; 
public var isNewFile : Boolean = false; 



/ * * 

* Initializes the app after loading 



*/ 

private function init() :void { 
file = new FileO; 
// Create root menu 

var rootMenu : NativeMenu = new NativeMenu () ; 
rootMenu . addSubmenu ( createFileMenu ( ) , "File") ; 

// Mac 

if (NativeApplication. supportsMenu) { 

NativeApplication . nativeAppli cat ion .menu = 
rootMenu ; 

} 

/ / Windows 

if (NativeWindow. supportsMenu) { 
nativeWindow . menu = rootMenu; 

} 

// Start out with a blank doc 
f ileNew(null) ; 

} 



public function fileNew(evt: Event) : void { 
file = File . desktopDirectory ; 
file = file.resolvePathCUntitled.txt"); 
isDirty = false; 
isNewFile = true; 
taEditor . text = ""; 
title = "AIRWrite - " + file.name; 
this . status = " " ; 



(continued) 
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Listing 1 0-3 (continued) 

taEditor . setFocus ( ) 



'} 

public function f ileOpen (evt : Event) :void { 

file . addEventListener (Event . SELECT, onFileSelect) 
f ile .browseForOpen ( "Open" ) ; 

} 



public function onFileSelect (evt : Event ): void { 
var f s : FileStream = new FileStream () ; 
f s . openAsync ( f ile , FileMode . READ) ; 
f s . addEventListener (Event .COMPLETE, onFileRead) 
f s . addEventListener (IOErrorEvent . IO_ERROR, 

onlOReadError ) ; 
isDirty = false; 
isNewFile = false; 
this . status = " " ; 

title = "AIRWrite - " + file. name; 
taEditor . setFocus ( ) ; 

} 

private function onFileRead (evt : Event) : void { 
var fs : FileStream = evt. target as FileStream; 
var str: String = f s . readUTFBytes ( f s . 

bytesAvailable) ,- 
taEditor . text = str; 
f s . close ( ) ; 

} 



public function f ileSave (evt : Event) : void { 
if ( ! isNewFile) { 

var fs : FileStream = new FileStream () ; 
fs .openAsync (file, FileMode .WRITE) ; 
f s . addEventListener (IOErrorEvent . IO_ERROR, 
onlOWriteError ) ; 
var str: String = taEditor . text ; 
str = str . replace (/ \r/g, "\n"); 
str = str . replace (/ \n/g, File . lineEnding) ; 
f s . writeUTFBytes (str) ; 
f s . close ( ) ; 
isDirty = false; 
this . status = " " ; 

} 

else { 

f ileSaveAs (evt) ; 

} 

} 



public function f ileSaveAs (evt : Event) : void { 
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file . addEventListener (Event . SELECT, 
onFileSaveAsSelect) ; 

file .browseForSave (" Save As") ; 

} 

public function onFileSaveAsSelect (evt : Event) : void 
{ 

if (isNewFile) { 

title = "AIRWrite - " + file. name; 
isNewFile = false; 

} 

f ileSave (evt) ; 



public function f ileExit (evt : Event) : void { 
NativeApplication. nativeApplication . exit ( ) ; 

} 

private function onlOReadError (evt : Event) : void { 
Alert . show (" Something wacky happened. We are 
unable to open " + f ile .nativePath, "Error", 
Alert. OK, this); 

} 

private function onlOWriteError (evt : Event) : void { 
Alert . show ( "We are really sorry, but the file 

cannot be saved. It's not our fault ... really !" , 
"Error", Alert. OK, this); 

} 

private function onChange (evt : Event) : void { 
this. status = "Modified"; 
isDirty = true; 

} 

* Creates the File menu for app 

*/ 

private function createFileMenu ( ) : NativeMenu { 
var mnu : NativeMenu = new NativeMenu () ; 
createMenuCommand ( mnu, 'New', 'n', null, 0, 
f ileNew) ; 

createMenuCommand ( mnu, 'Open', 'o', null, 0, 

f ileOpen) ; 
createMenuSeparator (mnu) ; 

createMenuCommand ( mnu, 'Save', 's', null, 0, 

f ileSave) ; 
createMenuSeparator (mnu) ; 
//If Mac OS X, then use Quit label 
if (NativeApplication . supportsMenu) { 
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createMenuCommand ( mnu, 'Quit', 'g', null, 0, 
fileExit) ; 

} 

//If Windows, then use Exit 
else { 

createMenuCommand ( mnu, 'Exit', 'x', null, 0, 
fileExit) ; 

} 

return mnu; 



I * * 

* Creates a "fully loaded" menu command based on 
parameters 

* 

*/ 

public function createMenuCommand (menuContainer : 

NativeMenu, itemLabel : String, itemKey: String, 
itemModif iers :Array, itemMnemonic : int, 

selectHandler : Function) : NativeMenu I tern { 
var cmd:NativeMenuItem= NativeMenu (menuContainer ) . 

addltem(new NativeMenuItem ( itemLabel ) ) ; 
cmd.mnemoniclndex = itemMnemonic; 
cmd.keyEguivalent = itemKey; 
if ( itemModif iers != null ) { 

cmd . keyEguivalentModif iers = itemModif iers ; 

} 

if (selectHandler != null ) { 

cmd. addEventListener (Event . SELECT, 
selectHandler) ; 

} 

return cmd; 

} 



I * * 

* Creates a menu separator 

*/ 

private function createMenuSeparator (menuContainer : 

NativeMenu) : NativeMenuItem { 
var sep : NativeMenuItem= NativeMenu (menuContainer ) . 

addltem(new NativeMenuItem ( "sep" , true) ) ; 
return sep; 

} 

] ]> 

</mx : Script> 

<mx:TextArea id= " taEditor " x="0" y= " 0 " width="100%" 
height= "100%" backgroundAlpha= "0.8" 
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fontFamily= " Courier New" f ontSize= " 14 " 

backgroundColor= "#000000" color= " #FFFFFF " 
change= " onChange ( event ) " / > 
indowedApplication> 



Figure 10-5 shows the Flex version of the app, which uses custom Flex 
chrome and features a semitransparent window. 
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Figure 10-5: 

Opening a 
text file in 
AIRWrite. 



<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional //EN" 
"http://www.w3.org/TR/xhtroll/DTD/)thtitill-tranaitional.dtd ,, > 
<html xmlns-"http://www.w3.org/1999/xhtml n > 
<head> 

<raeta http-equiv— "Content-Type" content— "text /html; char set- utf-8" /> 
<title>Window Launcher</title> 

<link type-"text/caa" href-"a33et3/default.css" rel-" stylesheet" /> 

<acript type— "text/ javascript" language— "JavaScript" src-"asaeta/AlRAliases. js"x/acript> 
<script type— "text/javascript" language-" JavaScript" 3rc-"aaaets/util. js"X/script> 
<acript type—" text/ javaacript" language- "JavaScript" 3rc-"aaaeta/winaanip- js"x/script> 
</head> 

<body> 

<hl>Welcome to Adobe AIR.</hl> 

<p>Don't go messin' with my Adobe AIR.</p> 

<input id>"btnLaunch" type— "submit" value- "Launch" /> 

</div> 

</body> 

</html> 
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Chapter 11 



rom AIRhead to Datahead: 
Working with Databases 



In This Chapter 

Introducing the SQLite local database engine 
Using SQL to communicate with the database 
Connecting to a local database 
Performing database commands 
Inserting data into a table 

Working with data that originated from a database 



m Batabases and Web apps have long been "peas in a pod," two parts of a 
W>f solution that just work well together. The duo combine to serve as the 
foundation for the majority of Web apps. Adobe AIR enables you to connect 
to remote database servers through sockets or HTTP calls. However, it goes 
one step further: As does a true desktop app, Adobe AIR allows you to store 
database info in a local SQL database. 

In this chapter, I introduce you to the database connectivity of Adobe AIR. 
I begin by showing you how to connect your app to the SQLLite database 
engine to store and retrieve local data. I then walk you through various SQL 
commands to interact with the database. In fact, you could find yourself feel- 
ing so productive with databases that you might even begin thinking of your- 
self as a datahead. 



Working With Local databases 

I mention in Chapter 1 that Adobe AIR runtime includes SQLite, a SQL rela- 
tional database engine that enables you to work with a local database. Here 
are some facts to keep in mind when working with databases in AIR: 
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The database file that you work with is a local file with a name and 
extension you specify (often with a . db extension). 



can connect to multiple databases within the same app. 



v 0 The AIR API database commands enable you to work local database 
files, not server-based systems. 

A local database provides several added capabilities for your AIR app. You 
can develop a stand-alone database app that does not require a live connec- 
tion to the Internet. You can create an application that stores network data 
as a local copy in the SQLite database, resynching with the main server-side 
database periodically. You can also use a database to store application-spe- 
cific data rather than use a local file to store that information. 

For info on SQLLite, go to www. sqlite . org. 



Introducing the Basics of SQL 

All operations you perform on the database are not done with JavaScript 
or ActionScript. Instead, you use SQL. In case you're not familiar with SQL, 
the acronym stands for Structured Query Language, which is the standard 
database access language for interacting with databases. Using SQL, you can 
create or restructure tables, perform queries, and insert or modify records. 

In this section, I give you an overview of the basics of SQL. However, you 
need to keep in mind that SQL is a complex language. In fact, I could fill an 
entire For Dummies book on the subject. Oh, wait . . . someone already did 
that. For more on the SQL language, let me point you to SQL For Dummies, 
6th Edition, by Allen G. Taylor; you might also want to check out SQL Server 
2008 For Dummies, by Mike Chappie (both published by Wiley). 

In human speak, the basic form of a SQL statement is generally the following: 
Perform this operation on these fields in this table. For example, this statement: 

SELECT * FROM employee 

means select all records and all fields from the employee table. As you can 
infer, the * means all. 

Or, you can deal with specific fields: 

SELECT first_name, last_name FROM contact 

which means select all the first name and last name values from the employee 
table. 
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Of course, SQL commands can get much more complex, but these examples 
give you the basic idea. 



st to JavaScript and ActionScript, SQL is not case sensitive. 
Therefore, both of the following two commands are valid: 



select order_num from orders 
SELECT ORDERJJUM FROM ORDERS 



To help create readable code, the standard convention is to capitalize 
reserved words, such as SELECT and FROM, and enter field names and table 
names as lowercase. I follow this convention in the examples of this chapter. 

Let's look at the common SQL commands. I reference the sample database 
table in Table 11-1 for many of the examples in this chapter. 



Table 11-1 Sample Customer Table 



id 


first_name 


last_name 


City 


state 


100 


Art 


Vandelay 


Holden 


MA 


101 


Clark 


Kent 




Smallville 


K! 




102 


Nelson 


Rockenfelder 


Jericho 


K! 




103 


Kyle 


Exwh 


y Lapel IK 


I 


104 


Roy 


Kent 




Jericho 


K! 




104 


Rachel 


Armstrong 


Boston 


MA 



Handpickinq records With SELECT 

The select command is used to retrieve records from a table. The basic 
syntax is as follows: 

SELECT field_name(s) FROM table_name 

The set of records that is returned from the query is called the result set. 

For example, to return all the records from the customer table, you write: 

SELECT * FROM customer 

To return just the first and last names from the customer table, write this 
instead: 

SELECT first_name, last_name FROM customer 
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The result set of the preceding query looks like the following: 



DBodftsr 



Clark 

Nelson 

Kyle 

Roy 

Rachel 



last_name 

Vandelay 
Kent 

Rockenfelder 

Exwhy 

Kent 

Armstrong 



In some cases, fields in a table may contain duplicate values, which can be 
reflected in your result set. For example, if you want to return the states of 
the customer table, you can write: 



SELECT state FROM customer 



The following result set includes duplicate values: 



MA 
KS 
KS 
IN 
KS 
MA 



However, if you use the select distinct statement instead, the result set 
includes only unique values. Therefore: 



SELECT DISTINCT state FROM customer 



returns a result set with no duplicate values: 



MA 
KS 
IN 
KS 



Adding conditions With WHERE 

The where command enables you to specify conditions on the records that 
you want to return. The syntax is 

SELECT field_name(s) FROM table_name WHERE field_name operator value 



Chapter 11: From AIRhead to Datahead: Working with Databases 



For example, if you want to return the names of the customers who live in 
Kansas, you can use the following statement: 

FROM customer WHERE state= ' KS 1 

Note that the string value KS is enclosed in single quotation marks. Numeric 
values, however, are not enclosed in quotation marks. For example: 

SELECT * FROM customer WHERE id>101 

You use the greater than sign (>) as the operator in this query. The result set 
returns all the customer records that have an id value of greater than 101. 
You have several operators that you can use, as specified in Table 11-2. 



Table 11-2 


SQL WHERE Operators 




Operator 


Description 






Equ£ 


il 




<> 


Not 


aqual 




> 


Greaterthan 




< 


Less 


than 




>= 




Greaterthan or equal 




< = 




Less than or equal 




BETWEEN 




Between an inclusive range 




LIKE 


Search for a specific patten 





Sorting utitfi ORDER B\l 

You can specify the sort order of the result set by using the order by com- 
mand. Here's the general structure: 

SELECT field_name(s) FROM table_name ORDER BY f ield_name (s) ASC|DESC 

By default, the result is sorted in ascending order (asc). However, you can 
instead add the desc keyword at the end to sort in descending order. 

Here's an example of a sort: 

SELECT first name, last name FROM customer ORDER BY last name, first name DESC 
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The result set looks like this: 
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Nelson 

Roy 

Clark 

Kyle 

Rachel 



last_name 

Vandelay 

Rockenfelder 

Kent 

Kent 

Exwhy 

Armstrong 



Adding records With INSERT INTO 

To insert a new record into a database table, you use the insert into 



statement. Follow 


the general syntax shown here: 




INSERT INTO table, 
VALUES ( 'valuel ' 


name (fieldl, field2, field3 
, 'value2', 'value3') 


) 











As you can see, the field names themselves are not enclosed in quotation 
marks, but string values are inside the values parentheses. 



Here's an example of 


adding a new record to 


the customer table 




INSERT INTO customer 


(id, last_name, f irst_name, city, state) 





VALUES (105, 'Hammer', 'Jack', 'Chicago' 



'IL') 



Modifying records With UPDATE 

You can use the update statement to update existing records in your data- 
base table with new values. Check out the structure of a typical update 
statement: 

UPDATE table_name SET fieldl= 'valuel ' , f ield2= ' value2 ' , ... 
WHERE fieldX='valueY' 

In most cases, you want to have the where clause on the end of an update 
statement to determine which record or set of records to update. If you don't 
add the where clause, all the records in the table are updated to the values 
specified in the SET clause. 
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Getting rid of records With DELETE 
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3TE statement removes all the records from a table that match the 
pecified by the where clause. Check out the syntax: 



DELETE FROM table_name WHERE fieldx= ' valuel ' AND fieldY= 'value2 ' 
The following example deletes all customers from MA: 

DELETE FROM customer WHERE state='MA' 

Or, if you really, really want to, you can delete all records in the table by leav- 
ing off the where clause. For example: 



DELETE FROM customer 




You can also use the 


* keyword: 








DELETE * FROM custome 


r 






Creating a table With CREATE TABLE 

You use the create table statement to create a table in your database. In 
its simplest form, the syntax is as follows: 


CREATE TABLE table_name 
( 

fieldl data_type, 
field2 data_type, 
field3 data_type 

} 







Unsupported SQL Features in Adobe AIR 

The following SQL features are not available in t>* right outer join and full outer 
Adobe AIR: JOIN 

The triggers FOR each statement u 0 Updateable view 
and instead OF, as well as recursive 

V 0 GRANT and REVOKE 

triggers 

* -ru „„„ * * * Also, most alter table options are not 

V The foreign key statement 

supported, including drop column, alter 
j*" Nested transactions column, and add constraint. 
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The data type for a given field can be one of the types shown in Table 1 1-3. 
When a record is saved, the AIR runtime will attempt to convert the data value 
avaScript or ActionScript type into the type (more specifically called 
') of the field you specify. You can specify whether you want to allow 
null values in the field when you define the create table statement. 



Table 11-3 Adobe AIR Database Data Types 



Type 


Description 










text (or STRING) 


Allows normal storage of text. 




NUMERIC 


Allows you to store real, integer, or null values. 


INTEGER 


Integer values. 






REAL (or NUMBER) 


Forces numbers into floating point representation. 


BOOLEAN 


Contains true or false values. 




DATE 


Date values. 






XML 


For storing of XML structures. The ActionScript function 
xml ( ) is called to convert the incoming data into an XML 
structure. 


XMLLIST 


For storing of XML structures. The ActionScript function 
XMT.T.i st ( ) is called to convert the incomina data into 


an XML list. 







object For storing JavaScript or ActionScript object instances. 

Data is serialized in AMF3 format. 



NONE Data is inserted into the field without conversion. 



The following statement creates the customer table. Notice the if not 
exists clause, which tells the database to create the customer table only if 
the table has not been created before: 



CREATE TABLE IF NOT EXISTS customer 
( 

id INTEGER , 
first_name TEXT, 
last_name TEXT, 
city TEXT, 
state TEXT 



If you want to define a primary key to a field, you add primary key after the 
desired field: 



id INTEGER PRIMARY KEY, 
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A common desire is to have the primary key field be autoincrementing, 
freeing you from needing to generate a unique field value on your own. For 
suppose you'd like the id field to be autoincrementing. To make it 
pe: 



id INTEGER PRIMARY KEY AUTO INCREMENT , 



Following is a full example. If you want the id of your customer table to be 
autoincrementing, you define the table as follows: 



CREATE TABLE IF NOT EXISTS customer 
( 

id INTEGER PRIMARY KEY AUTO INCREMENT, 
first_name TEXT, 
last_name TEXT, 
city TEXT, 
state TEXT 



Then, when a new record is added, you don't specify the autoincrement field 
value but instead provide the remaining values: 

INSERT INTO customer (last_name, first_name, city, state) 
VALUES ('Hammer', 'Jack', 'Chicago', 'IL') 



Opening a database Connection 

Your first step in performing any database operation is to open a connection 
to a local database file. Just as with file system files, you can create either 
synchronous or asynchronous connections. (See Chapter 10 for an explana- 
tion of the difference between synchronous and asynchronous connections.) 

You create synchronous connections using open ( ) , and the commands on the 
database are performed sequentially in the order in which they occur in the 
source code. What's more, the app will wait on result of the operation from 
the database engine before continuing. 

For asynchronous connections, you use openAsync ( ) and add a handler to 
the connection's open event to perform operations on an open connection. 
When you establish an asynchronous connection, your AIR app hands off a 
SQL statement to the database engine for processing but doesn't wait for the 
results. The database engine takes the request and processes it in the back- 
ground. When the SQL statement has been completed, an event is dispatched 
in your app. 
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Perhaps the most practical distinction between open ( ) and openAsynch ( ) 
is that open ( ) waits to execute any more lines of code until the database 
^ration finishes. In contrast, openAsynch ( ) fires off the database 
m call but continues processing lines of code that appear below it. 
Therefore, if you have code that's dependent on the database connection 
being established, you want to place that code within the open event handler. 



is uiai ope 
^GrWo^pr; 



When you open a connection, AIR looks for the local file you specify. If that file 
is not found, a new database file is created for you. 

The following JavaScript function establishes a synchronous connection to 
a database called rss . db, located in the rssf eed subfolder of the user's 
documents directory: 

function connectDatabase ( ) { 

var dbRoot = air. File. documentsDirectory . resolvePath) "rssdrop" ) ; 

dbRoot . createDirectory ( ) ; 

dbFile = dbRoot . resolvePath ( "rss .db" ) ; 

sqlConnection = new air . SQLConnection ( ) ; 

sqlConnection.open(dbFile) ; 

//do something now 

} 

The resolvePath ( ) method assigns the rssf eed folder to the dbRoot 
variable. This folder is then created if necessary. The dbFile is assigned to 
the rss . db, which is the database file, which is then used as the parameter 
in the connection's open ( ) method. 

Here's the ActionScript equivalent: 

private function connectDatabase (): void { 

var dbRoot: File = File .documentsDirectory . resolvePath ( "rssdrop" ) ; 

dbRoot . createDirectory ( ) ; 

dbFile = dbRoot . resolvePath ( "rss .db" ) ; 

sqlConnection = new SQLConnection () ; 

sqlConnection. open(dbFile) ; 

//do something now 

} 

Alternatively, you can open the database asynchronously. To do so in 
JavaScript, use this code: 



function connectDatabase)) { 

var dbRoot = air. File. documentsDirectory. resolvePath! "rssdrop" ) ; 

dbRoot . createDirectory ( ) ; 

dbFile = dbRoot . resolvePath ( "rss .db" ) ; 

sqlConnection = new air . SQLConnection () ; 

sqlConnection. addEventListener (air . SQLEvent .OPEN, onDatabaseOpen) ; 
sqlConnection. addEventListener (air . SQLErrorEvent .ERROR, onDatabaseError) ; 
sqlConnection. openAsync (dbFile) ; 
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} 

. onDatabaseOpen ( event) { 

le ' s where you would do something with the open database 



private function onDatabaseError (event) { 

alert (event . error .message + " Details: " + event. error. details ) ; 

} 

As you can see, two event listeners are added. They are triggered when 
the database opens or when a database error occurs. The openAsynch ( ) 
method is then called to open the rss . db database. 

The ActionScript code is as follows: 

private function connectDatabase ( ) : void { 

var dbRoot: File = File .documentsDirectory. resolvePath ( 1 rssdrop ') ; 
dbRoot . createDirectory ( ) ; 

dbFile = dbRoot. resolvePath ( DATABASE_FILE ) ; 
sqlConnection = new SQLConnection ( ) ; 

sqlConnect ion. addEventListener (SQLEvent .OPEN, onDatabaseOpen) ; 
sqlConnection. addEventListener (SQLErrorEvent .ERROR, onDatabaseError) ; 
sqlConnection. openAsync (dbFile) ; 

} 

private function onDatabaseOpen (event : SQLEvent ) : void { 

// here's where you would do something with the open database 

} 

private function onDatabaseError (event : SQLErrorEvent ) : void { 

Alert . show (event . error .message + " Details: " + event . error .details) ; 

} 

After a database connection is established, you can either create a database 
table or perform an operation on an existing table. 

Performing Database Operations 
With SQLStatement 

You send SQL commands to the database by using a SQLStatement object. 
The SQLStatement object uses an open database connection to execute 
a SQL statement on the database. Adobe AIR allows you to work with the 
results of the SQL statement by attaching a handler to the result event, 
which is dispatched when the database finishes processing. In case of a prob- 
lem, you should also add a listener to the error event. 
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Here's a basic framework for opening a database and executing a SQL 
command: 



d Books 

database. 



in File object instance to local database file 
file = database_path.resolvePath( "database. db" ) ; 
// Create SQL connection 
sqlConnection = new air . SQLConnection ( ) ; 

// Open either synchronous or asynchronous connection on the database file 

sqlConnection. open (database_f ile) ; 

// Create SQL statement 

var statement = new air . SQLStatement () ; 

// Connect the dots 

statement . sqlConnection = sqlConnection; 

// Create SQL statement 

var sql = "MY SQL STATEMENT GOES HERE" 

statement . text = sql; 

// Add event handlers 

statement . addEventListener (air . SQLEvent . RESULT , onDatabaseCreated) ; 
statement . addEventListener (air . SQLErrorEvent . ERROR, onDatabaseError) ; 
// Execute SQL - process results in the SQLEvent . RESULT handler 
statement . execute ( ) ; 

The following sections show you how this framework works with a variety of 
SQL statements. 



Creating a Database Table 

Unless you are delivering your app with a pre-populated database, your first 
step will typically be to create one or more tables in which to store data. You 
do this by passing a create table SQL statement to the database. 

The following code assigns an open connection called sqlConnection to 
the SQLStatement instance's sqlConnection property. A SQL statement 
is created as a String variable and assigned to the text property of the 
SQLStatement. This SQL statement is passed to the database engine using 
execute ( ) for processing. The SQL statement itself tells the database to 
create a table named rss feeds if it does not already exist. Event handlers 
are provided to process the result of the statement. 

Check out the JavaScript code: 

function initializeDatabase ( ) { 

var createStmt = new air . SQLStatement () ; 
createStmt. sqlConnection = sqlConnection; 
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var sgl = 

CREATE TABLE IF NOT EXISTS rssfeeds (" + 

feedld INTEGER PRIMARY KEY AUTO INCREMENT, " + 
url TEXT UNIQUE, 11 + 
name TEXT, " + 
homeURL TEXT, " + 
lastFetched DATE" + 

" ) " ; 

createStmt . text = sql; 

createStmt . addEventListener (air . SQLEvent . RESULT , onDatabaseCreated) ; 
createStmt . addEventListener ( air . SQLErrorEvent . ERROR , onDatabaseError ) ; 
createStmt . execute ( ) ; 



function onDatabaseCreated)) { 

air .trace ( "You created your very own database table !!!!!") ; 

} 

function onDatabaseError)) { 

air . trace ( "Bummer, something went majorly wrong."); 

} 



Here is the ActionScript code: 



private function initializeDatabase ( ) : void { 

var createStmt : SQLStatement = new SQLStatement!); 
createStmt . sglConnection = sqlConnection; 
var sql: String = 

"CREATE TABLE IF NOT EXISTS rssfeeds (" + 

feedld INTEGER PRIMARY KEY AUTO INCREMENT, " + 

url TEXT UNIQUE, " + 

name TEXT, " + 

homeURL TEXT, " + 

lastFetched DATE" + 

" ) " ; 

createStmt . text = sql; 

createStmt . addEventListener (SQLEvent .RESULT, onDatabaseCreated) ; 
createStmt . addEventListener ( SQLErrorEvent . ERROR , onDatabaseError ) ; 
createStmt . execute ( ) ; 



private function onDatabaseCreated (event : SQLEvent ) : void { 
("You created your very own database table! !!!!"); 

} 

private function onDatabaseError)): void { 

trace ( "Bummer, something went majorly wrong."); 

} 
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a Record 

iwing code inserts a database record into the rssf eed database. 



Notice how it uses script variables in the SQL statement. 



In JavaScript: 

function addRecord ( ) { 

var url = "http://www.richwagnerwords.com/rss.xml"; 
var name = "Rich Wagner Blog"; 
var homeURL = "http://www.richwagnerwords.com"; 
var lastFetched = 12/31/2008 as Date; 
insertRecord ( url, name, homeURL, lastFetched); 



function insertRecord! url, name, homeURL, lastFetched) { 
var insertstmt = new air . SQLStatement ( ) ; 
insertStmt . sglConnection = sqlConnection; 
var sql: String = 

" INSERT INTO rssfeeds (url, name, homeURL, lastFetched) " + 
"VALUES ( ' " + url + " 1 , ' " + name + " 1 , 1 " + homeURL + " ' , " + lastFetched + 



" ) " ; 

insertStmt . text = sql; 
insertStmt . addEventListener (air 
insertStmt . addEventListener (air 
insertStmt . execute ( ) ; 

} 




SQLEvent .RESULT, onDatabaselnsert) ; 
SQLErrorEvent. ERROR, onDatabaseError) ; 


In ActionScript: 











private function addRecord () : void { 

var url:String = "http://www.richwagnerwords.com/rss.xml"; 
var name:String = "Rich Wagner Blog"; 
var homeURL : String = "http://www.richwagnerwords.com"; 
var lastFetched: Date = 12/31/2008 as Date; 
insertRecord! url, name, homeURL, lastFetched); 



private function insertRecord! url: String, name: String, homeURL: String, 
lastFetched:Date) : void { 

var insertStmt : SQLStatement = new SQLStatement ( ) ; 
insertStmt . sqlConnection = sqlConnection; 
var sql: String = 

"INSERT INTO rssfeeds (url, name, homeURL, lastFetched) " + 
"VALUES ( ' " + url + " ' , ' " + name + " ' , ' " + homeURL + " ' , " + lastFetched + 
" ) " ; 

insertStmt . text = sql; 

insertStmt .addEventListener (SQLEvent .RESULT, onDatabaselnsert) ; 
insertStmt . addEventListener (SQLErrorEvent . ERROR, onDatabaseError) ; 
insertStmt . execute ( ) ; 
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Here's a more complex Flex-based data entry example combining several of 
these database tasks as well as some other techniques that I discuss in other 



First, this example shows how to develop an app that provides a form-based 
interface in which to enter information on an RSS feed (see Figure 11-1). This 
information is then added into the database table. 



Figure 11-1: 

Simple data 
entry form. 



ubl: y 

Title: 
Home URL: 

Feea type: RSS 2.0 



Lest Fetchefl: 



The MXML layout is as follows: 

<mx:Text x="88" y="28" text="URL:
 " textAlign=" lef t" /> 
<mx:Text x="84" y="61" text="Title:&:#xd; " textAlign="left"/> 
<mx:Text x="56" y="93" text="Home URL:
" textAlign=" lef t " /> 
<mx:Text x="42" y="155" text="Last Fetched: " textAlign="left"/> 
<mx:TextInput id="tiURL" x= ,, 138" y= ,, 26 M width="185"/> 
<mx:TextInput id="tiTitle" x="138" y="59" width="185"/> 
<mx:TextInput id= ,, tiHomeURL" x="138" y="91" width="185"/> 
<mx:DateField id="dfLastFetched" x="138" y="153"/> 
<mx:Button x="270" y="192" label=" Insert" click="onInsertClick ( ) " /> 
<mx:Text x="56" y="121" text="Feed type:" textAlign=" lef t " /> 
<mx:ComboBox id="cbType" x="138" y="119" width="185"> 
<mx : dataProvider> 

<mx:String>RSS 2 . 0</mx: String> 

<mx:String>RSS 1 . 0</mx: String> 

<mx : String>Atom< /mx : String> 
</mx:dataProvider> 
< /mx : ComboBox> 

The following code shows the initialization routine in which the database is 
opened and the table is created if it does not exist: 

static private const DATABASE_FILE : String = "rssfeeds .db" ; 

private var dbFile: File- 
private var sqlConnection:SQLConnection; 
private var feedURL: String; 
private var feedTitle: String; 
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private var homeURL: String; 
private var lastFetched: String; 
ate var feedType: String; 



// Initialize app 
private function init ( ) : void 
{ 

connectDatabase ( ) ; 



// Connect to database 

private function connectDatabase!) : void 
{ 

var dbRoot: File = File .documentsDirectory. resolvePath ( 1 rssdrop 1 ) ; 
dbRoot . createDirectory ( ) ; 

dbFile = dbRoot. resolvePath (DATABASE_FILE) ; 
sqlConnection = new SQLConnection ( ) ; 

sqlConnect ion. addEventListener (SQLEvent .OPEN, onDatabaseOpen) ; 
sqlConnection. addEventListener (SQLErrorEvent .ERROR, onDatabaseError) ; 
sqlConnection.openAsync (dbFile) ; 

) 

// Initialize database once the connection is opened 
private function onDatabaseOpen (event : SQLEvent ) : void 
{ 

initializeDatabase ( ) ; 

) 

// Database error 

private function onDatabaseError (event : SQLErrorEvent ) : void 
{ 

Alert. show (event. error. message + " Details: " + event. error. details ) ; 

) 

// Create database table, if it does not exist 
private function initializeDatabase!) : void 

{ 

var createStmt : SQLStatement = new SQLStatement ( ) ; 
createStmt . sqlConnection = sqlConnection; 
var sql: String = 

"CREATE TABLE IF NOT EXISTS rssfeeds (" + 

feedld INTEGER PRIMARY KEY AUTO INCREMENT, " + 

url TEXT UNIQUE, " + 

title TEXT, " + 

feedType TEXT, " + 

homeURL TEXT, " + 

lastFetched DATE" + 

" ) " ; 

createStmt . text = sql; 
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creates tmt . addEventListener (SQLEvent .RESULT, onDatabaseCreated) ; 
createStmt . addEventListener (SQLErrorEvent . ERROR, onDatabaseError) ; 
eateStmt . execute ( ) ; 



// Creation handler 

private function onDatabaseCreated (event : SQLEvent ) : void 
{ 

trace ("Table created."); 

) 



Note that the url field adds a new SQL operator named UNIQUE, which 
ensures that only unique RSS feeds can be added to the system. 

Next, when the user clicks the Insert button, the contents of the fields are 
used in a SQL statement to the open database. Here's the code related to 
inserting user data into the database: 

// Insert record into the table 

private function insertRecord ( url: String, title : String, feedType: String, 
homeURL: String, lastFetched: String) : void 

{ 

var insertstmt : SQLStatement = new SQLStatement ( ) ; 
insertStmt . sglConnection = sqlConnection; 
var lfDate:Date = lastFetched as Date; 
var sql: String = 

" INSERT INTO rssfeeds (url, title, feedType, homeURL, lastFetched) " + 
"VALUES ( "' + 

url + " ' , 1 " + title + " 1 , 1 " + feedType + " 1 , ' " + homeURL + 
" + lfDate 
+ ")"; 
insertStmt . text = sql; 

insertStmt . addEventListener (SQLEvent .RESULT, onDatabaselnsert ) ; 
insertStmt . addEventListener (SQLErrorEvent . ERROR, onDatabaseError) ; 
insertStmt . execute ( ) ; 

) 



// When insert is successful... 

private function onDatabaselnsert (event : SQLEvent ) : void 
{ 

Alert . show ( "Feed successfully inserted!"); 
clearFields ( ) ; 

) 

// Handler for Insert button click 
private function onlnsertClick ( ) : void 
{ 

var d: String = df LastFetched. selectedDate as String; 
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insertRecord ( tiURL.text, tiTitle.text, cbType.text, tiHomeURL.text, d) ; 
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lear all UI fields 
private function clearFields ( ) : void 

tiURL.text = ""; 
tiHomeURL.text = 
tiURL.text = ""; 
cbType . text = " " ; 



Figure 11-2 shows the result that appears on-screen. 




Figure 11-2: 

The data- 
base is 
happy it 
got a new 
record. 

^^^^H I 

Rather than stop there, you can add one additional way to add data into the 
database table: through drag-and-drop of an RSS feed onto the app. To do so, 
you begin by adding two drag-and-drop event listeners to the init ( ) function: 

addEventListener (NativeDragEvent .NATIVE_DRAG_ENTER, onDragln) ; 
addEventListener (NativeDragEvent . NATIVE_DRAG_DROP , onDragDrop ) ; 

You then add the two handlers for these events to accept dragged-in URLs: 

// Drag In handler 

public function onDragln (event : NativeDragEvent ) : void 
{ 

NativeDragManager.dropAction = NativeDragActions .COPY; 

if (event .clipboard. hasFormat (ClipboardFormats .URL_FORMAT) ) 

{ 

NativeDragManager . acceptDragDrop ( this) ; 

} 

} 

// Drop handler 

public function onDragDrop (event : NativeDragEvent) : void 
{ 
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if (event .clipboard. hasFormat (ClipboardFormats .URL_FORMAT) ) { 
feedURL = (event . clipboard. getData (ClipboardFormats .URL_FORMAT, 

ClipboardTransf erMode . ORIGINAL_PREFERRED) as String); 
idropFeed(feedURL) ; 



} 



The onDragDrop ( ) function captures the URL dropped onto the app and 
passes it to the dropFeed ( ) function, which follows: 

// Retrieve feed info via HTTPService 
public function dropFeed (url : String) : void 



CursorManager . setBusyCursor ( ) ; 

var httpService: HTTPService = new HTTPService!); 
httpService . resultFormat = "object"; 

httpService . addEventListener (ResultEvent .RESULT, onFetchComplete) ; 
httpService . addEventListener (FaultEvent . FAULT, onFetchError) ; 
httpService. url = url; 
httpService . send ( ) ; 



See Chapter 9 for more details on drag-and-drop. 

Before the app can add the RSS feed as a record into the table, it needs 
to gather additional field-related info. To have it do so, you can use an 
HTTPService object to retrieve that information directly from the feed itself. 
(See Chapter 12 for more on connecting to network resources in AIR apps.) 
Note that the onFetchComplete ( ) function is the handler that is triggered 
when the HTTPService object returns a result. Here's the code: 

// Handler for HTTPService result event 
// Retrieve info for record 

private function onFetchComplete (event : ResultEvent) : void 
{ 

// RSS 2.0 

if (event . result . hasOwnProperty ( "rss" ) ) 

{ 

feedTitle = event. result. rss. channel. title as String; 
homeURL = event . result . rss . channel . link as String; 
lastFetched = event. result. rss. channel. lastBuildDate as String; 
feedType = "RSS 2.0"; 

) 

// RSS 1.0 

else if (event . result .hasOwnProperty ( "RDF" ) ) 

{ 

feedTitle = event. result. RDF. channel. title as String; 
homeURL = event . result .RDF . channel . link as String; 
lastFetched = event. result. RDF. channel. lastBuildDate as String; 
feedType = "RSS 1.0"; 

) 

// Atom 
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else if (event . result .hasOwnProperty (" feed" ) ) 
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feedTitle = event. result. feed. title as String; 
'homeURL = event . result . feed. link [0] as String; 
lastFetched = event. result. feed. updated as String; 
lastFetched = lastFetched. replace ( /-/g, "/ " ) ; 
lastFetched = lastFetched. replace ( "T" , " "); 
lastFetched = lastFetched. replace ( "Z" , " GMT-0000"); 
feedType = "Atom" ; 

) 

/ / Unsupported 
else 

{ 

trace ( "Unable to retrieve RSS feed: Unsupported format."); 
return; 

) 



clearFields ( ) ; 

insertRecord ( feedURL, feedTitle, feedType, homeURL, lastFetched); 
CursorManager . removeBusyCursor ( ) ; 

} 

// Error handler for HTTPService 
private function onFetchError (event : FaultEvent) : void 
{ 

CursorManager . removeBusyCursor ( ) ; 

trace ("The following error occurred when fetching the RSS feed: " + event, 
message) ; 

) 



Listing 11-1 provides the full source code for this app. 



Listing 11-1: rssdrop.mxml 

<?xml version=" 1 . 0 " encoding="utf -8 " ?> 

<mx:WindowedApplication xmlns :mx="http : / /www. adobe . com/2006/mxml " 
layout= " absolute " 
applicationComplete= " init ( ) " height="276" width="378"> 



<mx:Script> 
<! [CDATA [ 

import mx.rpc.http. HTTPService; 
import flash. data . SQLConnection; 
import flash. data. SQLStatement; 
import flash. events . SQLErrorEvent ; 
import flash. events. SQLEvent; 
import mx. controls .Alert ; 
import mx. collections . ArrayCollect ion; 
import mx. managers .CursorManager ; 
import mx. rpc . events .FaultEvent ; 
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private var dbFile: File; 

private var sqlConnection :SQLConnection; 

private var feedURL: String; 

private var feedTitle: String; 

private var homeURL: String; 

private var lastFetched: String; 

private var feedType: String; 

// Initialize app 

private function init ( ) : void 

{ 

connectDatabase ( ) ; 

addEventListener (NativeDragEvent .NATIVE_DRAG_ENTER, onDragln) ; 
addEventListener (NativeDragEvent .NATIVE_DRAG_DROP, onDragDrop) ; 



// Connect to database 

private function connectDatabase!) : void 
{ 

var dbRoot: File = File .documentsDirectory . resolvePath ( ' rssdrop 1 ) ; 
dbRoot . createDirectory ( ) ; 

dbFile = dbRoot. resolvePath (DATABASE_FILE) ; 
sqlConnection = new SQLConnection ( ) ; 

sqlConnection. addEventListener (SQLEvent .OPEN, onDatabaseOpen) ; 
sqlConnection. addEventListener (SQLErrorEvent . ERROR, onDatabaseError) ; 
sqlConnection. openAsync (dbFile) ; 

) 

// Initialize database once the connection is opened 
private function onDatabaseOpen (event : SQLEvent ) : void 
{ 

initializeDatabase ( ) ; 

) 

// Database error 

private function onDatabaseError (event : SQLErrorEvent ) : void 
{ 

Alert. show (event. error. message + " Details: " + event. error. details ) ; 

) 

// Create database table, if it does not exist 
private function initializeDatabase!) : void 

{ 

var createStmt : SQLStatement = new SQLStatement!); 



import mx . rpc . events . ResultEvent ; 




lie private const DATABASE_FILE : String = "rssfeeds .db" ; 



(continued) 
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createStmt . sglConnection = sqlConnection; 
r sql: String = 

CREATE TABLE IF NOT EXISTS rssfeeds (" + 

feedld INTEGER PRIMARY KEY AUTO INCREMENT, " + 
url TEXT UNIQUE, 11 + 
title TEXT, " + 
feedType TEXT, " + 
homeURL TEXT, " + 
lastFetched DATE" + 

)"; 

createStmt . text = sql; 

createStmt . addEventListener (SQLEvent .RESULT, onDatabaseCreated) ; 
createStmt . addEventListener (SQLErrorEvent . ERROR, onDatabaseError) ; 
createStmt . execute ( ) ; 



// Creation handler 

private function onDatabaseCreated (event : SQLEvent ) : void 
{ 

trace ("Table created."); 

) 

// Insert record into the table 
private function insertRecord ( url: String, title : String, feedType: String, 
homeURL: String, lastFetched: String) : void 

{ 

var insertStmt : SQLStatement = new SQLStatement!); 
insertStmt . sqlConnection = sqlConnection; 
var lfDate:Date = lastFetched as Date; 
var sql: String = 

"INSERT INTO rssfeeds (url, title, feedType, homeURL, lastFetched) " + 
"VALUES ( '" + 

url + " 1 , 1 " + title + " ' , 1 " + feedType + " 1 , 1 " + homeURL + " 1 , 
" + lfDate 
+ ")"; 
insertStmt . text = sql; 

insertStmt . addEventListener (SQLEvent .RESULT, onDatabaselnsert ) ; 
insertStmt . addEventListener (SQLErrorEvent . ERROR, onDatabaseError) ; 
insertStmt . execute ( ) ; 

) 

// When insert is successful... 

private function onDatabaselnsert (event : SQLEvent ) : void 
{ 

Alert . show ( "Feed successfully inserted!"); 
clearFields ( ) ; 

) 



// Handler for Insert button click 
private function onlnsertClick ( ) : void 
{ 

var d:String = df LastFetched. selectedDate as String; 
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insertRecord ( tiURL.text, tiTitle.text, cbType.text, tiHomeURL.text, d) ; 



private function clearFields ( ) : void 
{ 

tiURL.text = ""; 
tiHomeURL.text = " " ; 
tiURL.text = ""; 
cbType . text = " " ; 



// Drag In handler 

public function onDragln (event : Nat iveDragEvent) : void 
{ 

NativeDragManager.dropAction = NativeDragActions .COPY; 

if (event .clipboard. hasFormat (ClipboardFormats .URL_FORMAT) ) 

{ 

NativeDragManager . acceptDragDrop ( this) ; 

} 



// Drop handler 

public function onDragDrop (event : Nat iveDragEvent) : void 
{ 

if (event .clipboard. hasFormat (ClipboardFormats .URL_FORMAT) ) { 
feedURL = (event . clipboard. getData (ClipboardFormats .URL_FORMAT, 

ClipboardTransf erMode . ORIGINAL_PREFERRED) as String); 
dropFeed ( f eedURL) ; 



// Retrieve feed info via HTTPService 
public function dropFeed (url : String) : void 
{ 

CursorManager . setBusyCursor ( ) ; 

var httpService: HTTPService = new HTTPService!); 
httpService.resultFormat = "object"; 

httpService . addEventListener (ResultEvent .RESULT, onFetchComplete) ; 
httpService . addEventListener (FaultEvent .FAULT, onFetchError) ; 
httpService. url = url; 
httpService. send ( ) ; 

) 

// Handler for HTTPService result event 
// Retrieve info for record 

private function onFetchComplete (event : ResultEvent) : void 
{ 

// RSS 2.0 

if (event .result . hasOwnProperty ( "rss" ) ) 

{ 




Hear all UI fields 



(continued) 
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Listing 11-1 (continued) 

feedTitle = event . result . rss . channel . title as String; 
homeURL = event . result . rss . channel . link as String; 
lastFetched = event. result. rss. channel. lastBuildDate as String; 
feedType = "RSS 2.0"; 
) 

// RSS 1.0 

else if (event . result .hasOwnProperty ( "RDF" ) ) 

{ 

feedTitle = event . result .RDF . channel . title as String; 
homeURL = event . result .RDF . channel . link as String; 
lastFetched = event. result. RDF. channel. lastBuildDate as String; 
feedType = "RSS 1.0"; 

) 

// Atom 

else if (event . result .hasOwnProperty (" feed" ) ) 

{ 

feedTitle = event. result. feed. title as String; 
homeURL = event . result . feed. link [0] as String; 
lastFetched = event . result . feed. updated as String; 
lastFetched = lastFetched. replace (/-/g, "/"); 
lastFetched = lastFetched. replace ( "T" , " "); 
lastFetched = lastFetched. replace ( "Z" , " GMT-0000"); 
feedType = "Atom" ; 

) 

// Unsupported 

else 

{ 

trace ( "Unable to retrieve RSS feed: Unsupported format."); 
return; 

) 

clearFields ( ) ; 

insertRecord ( feedURL, feedTitle, feedType, homeURL, lastFetched); 
CursorManager . removeBusyCursor ( ) ; 

} 

// Error handler for HTTPService 

private function onFetchError (event :FaultEvent) : void 

{ 

CursorManager . removeBusyCursor ( ) ; 

trace("The following error occurred when fetching the RSS feed: " + event, 
message) ; 

) 

]]> 

</mx:Script> 

<mx:Text x="88" y="28" text="URL:
 " textAlign="left"/> 
<mx:Text x="84" y="61" text="Title:
 " textAlign="left"/> 
<mx:Text x="56" y="93" text="Home URL:
" textAlign=" lef t " /> 
<mx:Text x="42" y="155" text="Last Fetched: " textAlign=" lef t " /> 
<mx:TextInput id="tiURL" x="138" y="26" width="185"/> 
<mx:Text!nput id="tiTitle" x="138" y="59" width="185"/> 
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<mx: Text Input id="tiHomeURL" x="138" y="91" width="185"/> 
<mx:DateField id="dfLastFetched" x="138" y="153"/> 

tton x="270" y="192" label=" Insert" click="onInsertClick ( ) " /> 
xt x="56" y="121" text="Feed type:" textAlign=" lef t " /> 
ComboBox id="cbType" x="138" y="119" width="185"> 
<mx : dataProvider> 

<mx:String>RSS 2 . 0</mx: String> 
<mx:String>RSS 1 . 0</mx: String> 
<mx : String>Atom< /mx : String> 
< /mx : dataProvider> 
< /mx : ComboBox> 

</mx:WindowedApplication> 



Requesting Data front a Table 

When you perform a select query on a table, you execute the SQL 
statement in much the same way as you do the create new and insert 
examples shown in the previous sections. However, the key aspect of a 
select statement is processing the result set that is returned to you from 
the database. 

Consider the following HTML/JavaScript example that demonstrates how to 
work with the result set of the rssf eed . db database that is created earlier 
in this chapter. The app is simple (see Figure 1 1-3); it consists of a single 
button that, when clicked, queries the database and returns all the records 
from the rssf eeds table. The title and URL of the RSS feed are then dis- 
played in a bulleted list. 



DataDisplay 



Display RSS Feeds 



Figure 11-3: 

Ready to get 
a list of RSS 
feeds with 
the push of 
a button. 
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Here is the initial HTML file: 
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e>DataDisplay</title> 



<link href =" style. ess" rel=" stylesheet" type=" text/ess" /> 
<script type="text/javascript" src="AIRAliases . js"x/script> 

<script type= "text/ javascript "> 

</script> 

</head> 

<body> 

<div id=" container "> 

<p style="text-align:center"> 

<button type= "button" >Display RSS Feeds</buttonx/p> 



After this document shell is created, you're ready to establish a connection 
to the database file when the app opens. Here's the code: 

// Add event listener when app loads 

window. addEventListener (" load" , init, false); 

// Global vars 

var DATABASE_FILE = "rssfeeds .db" ; 
var sqlConnection; 

// Initialize app 
function init ( ) 
{ 

connectDatabase ( ) ; 

} 

// Connect to database 
function connectDatabase)) 
{ 

var dbRoot = air .File .documentsDirectory . resolvePath ( 1 rssdrop 1 ) ; 
dbRoot . createDirectory ( ) ; 

dbFile = dbRoot. resolvePath (DATABASE_FILE) ; 
sqlConnection = new air . SQLConnection ( ) ; 

sqlConnection. addEventListener (air . SQLEvent .OPEN, onDatabaseOpen) ; 
sqlConnection. addEventListener (air . SQLErrorEvent .ERROR, onDatabaseError) ; 
sqlConnection. openAsync (dbFile) ; 

) 



</div> 

</body> 

</html> 



// Initialize database once the connection is opened 
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function onDatabaseOpen ( event) 

trace) "Database connection is opened." ) ; 



// Database error 

function onDatabaseError (event) 

{ 

alert (event .error .message + " Details: " + event . error .details) ; 

} 

The init ( ) function is executed when the app loads and then calls the 
connectDatabase ( ) function. If you read the earlier section on connecting 
to a database, this code should look familiar. 

The database connection is now open and ready for action. 

Next, you add an onclick event handler for the HTML button named 
selectFromDatabase ( ) . This function is responsible for calling the SQL 
query on the rss feeds table: 



// Insert record into the table 
function selectFromDatabase!) 
{ 

selectStmt = new air.SQLStatement ( ) ; 
selectStmt.sqlConnection = sqlConnection; 
var sql = "SELECT * FROM rssfeeds"; 
selectStmt . text = sql; 

selectStmt . addEventListener ( air . SQLEvent . RESULT , onSelectResult ) ; 
selectStmt . addEventListener (air . SQLErrorEvent .ERROR, onDatabaseError) ; 
selectStmt . execute ( ) ; 

} 

In this function, the select SQL statement is passed onto the database 
engine for processing. The onSelectResult ( ) function is assigned to be 
the handler for the result event, which is triggered when the SQL query 
finishes. 

The selectStmt is defined globally so that it can be accessed from the 
onSelectResult ( ) function. 

Here's the onSelectResult ( ) function, which takes the results and adds 
the content to the DOM: 

function onSelectResult (event) 
{ 

var result = selectStmt .getResult () ; 
var len = result .data . length; 
for (i = 0; i < len; i++) 
{ 



Part III: Programming the Adobe AIR API 



var record = result. data [ i] ; 
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r c = document .getElementByld (' container ') ; 
ul_tag = document . createElement ( 1 ul ' ) ; 
c . appendChild (ul_tag) ; 
var li_tag = document . createElement ( 1 li ' ) ; 
li_tag. appendChild (document . createTextNode (record. title + 
+ ")" )); 
ul_tag.appendchild(li_tag) ; 



+ record. url 



} 



Figure 1 1-4 shows the results when this code is performed on the rssf eeds 
database table. 



flfifl DataDisplay 



Display RSS Feeds { 

• The Unofficial Apple Weblog (TUAW) (http://www.tuaw.oom/rss.xml) 

• Digg / Apple (http://rjigg.com/rss/indexapple.xml) 

• Wired Top Stories (http://www.wired.com/rss/index.xml) 

• Engadget (http://feeds.engadget.com/weblogsinc/engadget) 

• MacOSXHints.com (http://feeds.macosxhints.com/macosxhints/recent) 

• Ars Technica (http://feeds.feedburner.com/arstechnica/BAa''} 

Figure 11-4' * 0fficeTal| y< ntl P : '" ee<)sfeetil,umercom ' 0,ficeta|| y) 

Data that * Dar i n 9 Fireball (http://daringfireball.net/index.xml) 

Came fresh • Monoscope (http://www.monoscope.com/atom.xml) 

from a local 
database. 



Listing 1 1-2 provides a full listing of the HTML/JavaScript source code. 
Listing 11-2: DataDisplay.html 

<html> 
<head> 

<title>DataDisplay</title> 

<script type=" text /javascript" src="AIRAliases . js"x/script> 

<script type= "text/ javascript "> 

// Add event listener when app loads 

window. addEventListener (" load" , init, false); 

// Global vars 

var DATABASE_FILE = " rssf eeds .db" ; 
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connectDatabase ( ) ; 

} 

// Connect to database 
function connectDatabase!) 
{ 

var dbRoot = air .File .documentsDirectory. resolvePath (' rssdrop ') ; 
dbRoot . createDirectory ( ) ; 

dbFile = dbRoot. resolvePath (DATABASE_FILE) ; 
sqlConnection = new air . SQLConnection ( ) ; 

sqlConnection. addEventListener (air . SQLEvent .OPEN, onDatabaseOpen) ; 
sqlConnection. addEventListener (air . SQLErrorEvent . ERROR, onDatabaseError) ; 
sqlConnection. openAsync (dbFile) ; 

} 

// Initialize database once the connection is opened 

function onDatabaseOpen (event) 

{ 

air. trace! "Database connection is opened." ) ; 

} 

// Database error 

function onDatabaseError (event) 

{ 

alert (event . error .message + " Details: " + event . error .details) ; 

} 

// Insert record into the table 
function selectFromDatabase ( ) 
{ 

selectStmt = new air.SQLStatement ( ) ; 
selectStmt . sqlConnection = sqlConnection; 
var sql = "SELECT * FROM rssfeeds"; 
selectStmt . text = sql; 

selectStmt . addEventListener ( air . SQLEvent . RESULT , onSelectResul t ) ; 
selectStmt . addEventListener (air . SQLErrorEvent . ERROR, onDatabaseError) ; 
selectStmt . execute ( ) ; 

} 

// When insert is successful... 
function onSelectResult (event) 
{ 

var result = selectStmt .getResult () ; 
var len = result .data . length; 



var sqlConnection; 
var selectStmt; 




(continued) 
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for (i = 0; i < len; i++) 
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r record = result .data [i] ; 

var c = document .getElementByld (' container 1 ) ; 
var ul_tag = document . createElement ( 1 ul ' ) ; 
c.appendChild(ul_tag) ; 

var li_tag = document . createElement ( 1 li ' ) ; 

li_tag . appendchild (document . createTextNode (record. title + " (" + record, 
url + ")" )); 
ul_tag.appendchild(li_tag) ; 

} 

} 



</script> 

</head> 

<body> 

<div id=" container "> 

<p style="text-align:center"xbutton type="button" onclick="selectFromDatabase ( ) 
;">Display RSS Feeds</buttonx/p> 



</div> 

</body> 

</html> 
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Net Connectivity 



In This Chapter 

► Detecting network connectivity 

Monitoring a remote network resource 
Establishing an XML socket connection 
Creating a push server connection 

••••••••••••••••••••••••••••••••••••••••••••••••a 

s I say at the start of this book, Adobe AIR is designed to create rich 
¥ \ Internet applications (RIAs). Given that "Internet" is the middle word of 
that acronym, it's natural that AIR would provide network support. 

In this chapter, I introduce you to some key network capabilities of AIR that 
you'll find yourself wanting to incorporate into your app. You can discover 
how to detect whether the app has access to the Internet. You also explore 
how to communicate with a server using XML sockets. Finally, I round out the 
discussion by showing you how to push data from a server right into your 
AIR app. 



Detecting NeWork Connectivity 

If you're developing a traditional Web application, you can assume the need 
for Internet connectivity for your app when you're building it. After all, if 
users do not have a connection, they'll either be unable to access it at all or 
they won't be able to complete a task because a server is required. 



Part III: Programming the Adobe AIR API 



in a aesKt 

DropBoolSg 

Second, if 



An Adobe AIR application, however, is different. A live connection when running 
in a desktop environment may or may not be available. As a result, AIR enables 
tect changes to Internet connectivity in two ways. First, you can detect 
nges by trapping for the event of the nativeApplication object. 
Second, if you want to detect changes to a specific network resource, such as 
an IP address or Web site, you can use a service monitor. (For information on 
remote service monitoring, see the upcoming "Monitoring Remote Network 
Services" section.) 



If you'd simply like to know whether a change has occurred in the connection 
status of your app, add an event listener to the network_change event of 
the application. In JavaScript, you can add the following code: 

// Add event listener to init ( ) function 
air .NativeApplication. nativeApplication. addEventListener 
( air . Event . NETWORK_CHANGE , onNetworkChange ) ; 

function onNetworkChange (event) { 

Alert ( "Network change detected. Seek shelter immediately."); 

} 



The ActionScript equivalent is the following: 

// Add event listener to init() function 

NativeApplication. nativeApplication. addEventListener (Event . NETWORK_CHANGE , 
onNetworkChange) ; 



public function onNetworkChange (evt : Event ): void { 

mx. controls .Alert . show ( "Network change detected. Seek shelter immediately."); 

} 



Suppose you run an app with this code in it and unplug your network cable 
to disconnect your laptop from your home network. The app would quickly 
notice that a change occurred and show the alert message. Then, when you 
reconnected to the Internet using WIFI, the alert message would trigger once 

jftBEft again - 

You can't use this event to detect the exact nature of the network change, only 
that some sort of connection change occurred. 




Monitoring Remote NeWork Services 

Although the application's network_change event can be helpful, it also can 
be incomplete. Specifically, in a real world situation, when you want to deter- 
mine whether you've experienced a connectivity change, what you really 
want to know is whether a change in connection has occurred with a specific 
network resource your application needs. 
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Adobe AIR provides network service monitoring capabilities to detect 
changes in connectivity to a given HTTP or socket connection. For HTTP 
u use the URLMonitor class, whereas socket connections require 

e SocketMonitor. Both URLMonitor and SocketMonitor are 
children of the ServiceMonitor base class. 



The ServiceMonitor class and its children use an event-based approach to 
respond to network connectivity changes. To do so, they dispatch a status 
event whenever a change in network connection is discovered. You can then 
add an event listener to do something based on the change. 

To activate an instance of ServiceMonitor, call its start ( ) method. 




By default, a service monitor kicks in and polls the specified network resource 
only after the start ( ) method is called and when the network status changes 
(from the application's network_change event). However, by setting its 
polllnterval property to a specified number of milliseconds, you can 
have the service monitor check periodically independent of the application's 
NETWORK_CHANGE event. 



Enabling HTML apps for 
sen/ice monitoring 

For HTML apps, network service monitoring is outside the normal AIR appli- 
cation framework that you're used to working with by now. As a result, you 
need to perform two tasks to enable your app for monitoring: 

1. Copy the serviceraonitor . swf file from the frameworks subdirec- 
tory of the Adobe AIR SDK into your root application directory. 

This gives you access to ServiceMonitor and its descendents. 

2. Add the following script reference to your document head to include 

servicemonitor . swf in your app: 

<script source=" servicemonitor . swf " type="application/x-shockwave- flash" /> 

After you've added this reference, you're ready to go perform network moni- 
toring to your heart's content. 



Monitoring connectivity to a Web site 

The URLMonitor object comes in handy when you need to check on the con- 
nectivity to make HTTP or HTTPS requests to a given URL. The URLMonitor 
object is designed for checking connectivity at port 80, the standard port for 
HTTP communication. 
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The typical way to use URLMonitor is to create an instance of the class, 
assign a URL to it, and attach an event listener to it when the connection 



For example, use the following HTML/JavaScript code to detect connectivity 

to google . com: 

<script src="servicemonitor.swf " type="application/x-shockwave-f lash" /> 

<script> 

var urlMonitor; 

function init ( ) { 

urlMonitor = new air .URLMonitor (new air .URLRequest ( 'http: //www. google. com 1 )) ; 
urlMonitor . addEventListener (air . StatusEvent . STATUS , onStatusChange) ; 
urlMonitor . start ( ) ; 

} 

function onStatusChange (event) { 
if (urlMonitor . available) { 

alert ("The current network status is A-OK!"); 

} 

else 

alert ("The current network status is BAD, AWFUL, and OTHERWISE TERRIBLE."); 

} 

} 

</script> 

As you can see, the URLMonitor instance uses a URLRequest instance in 
its constructor to determine the exact resource to monitor. After assign- 
ing a listener to the status event, the onStatusChange handler tests the 
URLMoni tor's available property to determine whether the resource is 
available. 

Here's a similar example using ActionScript: 

import air .net . SocketMonitor; 
import mx. controls .Alert ; 
import air .net .URLMonitor ; 
import flash.net .URLRequest ; 
import flash. events . StatusEvent ; 

private static const TEST_URL : String = 1 http : //www. dummies . com 1 ; 

private static const CODE_UNAVAILABLE: String = "Service. unavailable" ; 

private static const CODE_OK: String = " Service. available " ; 

private static const MSG_OK:String = "Site is accessible"; 

private static const MSG_UNAVAILABLE = "Site is unavailable. Please check 




your internet connection. 



public function init():void { 
var urlMonitor:URLMonitor; 
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var socketMonitor : SocketMonitor ; 

SIMonitor = new URLMonitor (new URLRequest (TEST_URL) ) ; 
IMonitor . addEventListener (StatusEvent . STATUS, onConnectionStatusChange) ; 
urlMonitor . start ( ) ; 
) 

public function onConnectionStatusChange (evt : StatusEvent ): void { 
if (evt. code == CODE_OK) { 
Alert . show (MSG_OK) ; 

) 

else if (evt. code == CODE_UNAVAILABLE ) { 
Alert . show(MSG_UNAVAILABLE) ; 

) 

) 

Notice the code property of the StatusEvent instance in the onConnection 
StatusChange handler. You can use it to determine whether the service is 
available. It has two values: 

Service . available 
Service . unavailable 

However, in general, it is considered better practice to use the available 
property of the ServiceMonitor instance rather than the event code. 

Monitoring socket connections 

The SocketMonitor object provides the same functionality as URLMonitor 
does when you need to work with socket connections to ports other than 80. 
Here is a JavaScript example that connects to an FTP server: 

<script src="servicemonitor . swf " type="application/x-shockwave-f lash" /> 
<script> 

var socketMonitor; 
function init ( ) { 

socketMonitor= new air . SocketMonitor (new air .URLReguest (' ftp : //ftp .dummies . 
com', 21)); 

socketMonitor . addEventListener (air . StatusEvent . STATUS, onStatusChange) ; 
socketMonitor. start ( ) ; 

} 

function onStatusChange (event) { 
if (socketMonitor. available) { 

alert ("The current socket connection is working!"); 

} 
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else 
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t( "Houston, we have a socket problem."); 



</script> 



Making an XML Socket Connection 

Adobe AIR provides a framework for creating both XML and binary socket 
connections with a server. An XML socket is useful when you want to keep 
a live connection open between your app and a server for exchanging data. 
So, not only can your app request data from or upload data to a server, but 
you can also have a server push information down to your app without user 
intervention. An XML socket, implemented through the XMLSocket class, is 
intended for XML data, but AIR does actually enforce an XML structure in the 
data you interchange. 

Establishing TCP/IP socket connection is a two-sided project. First, you need 
to enable your AIR client app for the data interchange. Second, a server- 
side process must be able to monitor the port and then process the data or 
instructions of your app when a connection is established. The server side 
app can be written in any traditional app server language, such as Java, PHP, 
Cold Fusion, Python, and so on. 




Keep in mind a couple of security restrictions when working with XML sock- 
ets. First, you can't connect to any port you want with XMLSocket. Because 
lower number ports are reserved for core services such as FTP, POP3, or 
HTTP, you can connect only to a port greater than or equal to 1024. Second, 
nonsandboxed content can connect to a server only in the same domain as 
the one in which the content resides. 

To show you how to create a socket connection, I first show you how to 
create a very basic Java server to handle your socket connection. I then walk 
you through creating the socket connection in your AIR app. 



Creating a basic socket seri/er 

A socket connection is much like a phone line. You can have the coolest 
phone in the world, but if no one is on the other end of the phone line to talk 
with you, what's the point? In the same way, if your AIR application is going 
to be able to converse with a remote server using a socket connection, then 
you need to have a backend server to talk to. 
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With that in mind, in this section I show you how to create a very simplistic 
Java server for this task. The server's job is simply to listen for a socket con- 
t a specified port, and when a conversation is started, the server 
ints that text to a console window. Because this book is about 
Adobe AIR and not Java or any other server-side technology, I don't dwell on 
many of the details concerning how the server works. At a minimum, you can 
read the source code comments to get a better idea of what the Java server 
does. But if you'd like to know more about Java or how to create Java serv- 
ers, I recommend checking out Java For Dummies, 4th Edition, by Barry Burd 
(Wiley Publishing). 

If you expect to spend any time at all working with a Java server, I strongly 
recommend downloading the Eclipse IDE at http : / / eclipse . org. It's a 
free download and is an excellent way to work with and debug the Java server, 
even if you're a Java newbie. If not, find yourself a text editor and command 
prompt. 



1. If necessary, install the JDK (Java SE Developer's Kit). 

Before proceeding, you need to have the JDK installed. Mac OS X users 
already have this on their system. Windows users need to download and 
install from http : / / java . sun . com/ javase/ downloads /index . 
jsp. 

2. Create or download ReallySimpleServer . j ava. 

Listing 12-1, which follows these steps, shows the Java code for the 
simple server. You can type this code into a new text-based file and save 
it as ReallySimpleServer. java. 

Or, much easier, simply download ReallySimpleServer. java from 
this book's Web site at www. dummies . com/go/adobeairfd. 

3. Open a command-line window and change the directory to the loca- 
tion of the ReallySimpleServer . j ava file. 

4. From a command-line window, enter the following instruction from 
the same directory that the . j ava file is in: 

javac ReallySimpleServer . java 

This command compiles the source code and generates a 
ReallySimpleServer . class file. 

If javac is unrecognized, make sure that the JDK path is in your path. 

5. Run the Java server by typing the following command in a command- 
line window: 

java -classpath . ReallySimpleServer 



If you're using Eclipse, you can compile and run the server right from within 
the IDE. 
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Listing 12-1: ReallySimpleServer.java. 
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mport java.io.* 
j ava . net . 



class ReallySimpleServer { 
private static ReallySimpleServer server; 
ServerSocket socket; 
Socket incomingSocket; 
Buf f eredReader inputReader; 
PrintStream outputStream; 



// Called when ReallySimpleServer is launched 
public static void main (String [ ] args) { 
int port = 6101; 
try { 

port = Integer .parselnt (args [0] ) ; 

) 

catch (ArraylndexOutOfBoundsException e) { 
// Catch exception 

) 

// Create new server socket listener at specified port 
server = new ReallySimpleServer (port) ; 



private ReallySimpleServer ( int port) { 

System. out. println(«>>>>>>> Starting ReallySimpleServer - the Server to the 

Masses. . .Really!») ; 
System. out .println («Hey ya - talk to me. When you are done, send me a 

<closeConnection/> to guit.»); 

try { 

// Listen for socket connections 
socket = new ServerSocket (port) ; 
incomingSocket = socket . accept () ; 
// Incoming text 

inputReader = new Buf f eredReader (new InputStreamReader ( incomingSocket . 

getlnputstream( ) ) ) ; 
outputStream = new PrintStream ( incomingSocket .getOutputStream) )) ; 
boolean completed = false- 
while (! completed) { 

String str = inputReader . readLine ( ) ; 
// If incoming text is null 
if (str == null) { 

printout! «NULL VALUE: Hey, gimme a break. You gave me nothing!* ); 
completed = true; 

) 

// If all goes well, here's where the code will go to 
else { 

printout («Here ' s what you wrote: « + str + «\r») ; 

// If client closes connection, mark flag as true to leave loop 

if (str . trim( ) . equals («<closeConnection/>») ) { 
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completed = true; 

) 

J 

incomingSocket . close ( ) ; 
) 

catch (Exception e) { 
System. out .print In (e) ; 

) 

} 

// Prints output 

private void printout (String str) { 
outputStream.println(str) ; 
System. out .println (str) ; 

} 

} 



Adding a socket connection 

With the Java server waiting patiently for someone to talk to, it's time to 
develop a simple AIR app that sends data to it. After you have created the 
application shell in HTML, Flex, or Flash, you want to establish a socket con- 
nection to the server using the XMLSocket object. 

Begin by creating an instance of XMLSocket. Here's the code in JavaScript: 

var xmlSocket = new air. XMLSocket () ; 

In ActionScript: 

var xmlSocket : XMLSocket = new XMLSocket () ; 

You want to add event listeners to xmlSocket. For a simple conversation, 
you're concerned only with listening to connect and io_error events: 

xmlSocket. addEventListener ( [air. ] Event . CONNECT , onConnect) ; 
xmlSocket . addEventListener ( [air . ] IOErrorEvent . IO_ERROR, OnlOError) ; 

With that groundwork laid, you're ready to connect to the socket. For this 
demo, you're connecting to localhost at port 6101. 

xmlSocket . connect ( " localhost" , 6101) ; 
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After a connection is made, the server can accept XML data from the AIR app. 
To enable the server to do so, you use the send ( ) method. 



i, keep in mind a couple of important points on sending data: 



v 0 Each string you send over the socket connection needs to be terminated 
with a \n character combo. 

Be sure to place send ( ) statements in the onConnect handler. If you 
place them just after a connect ( ) statement, they could be called 
before the connection has been established. 



Here's the code in JavaScript: 



function onConnect (evt) { 

var cmdConnect = "<connect/> \n" ; 

var cmdLogin = "<login username=\ " ivan\ " password=\ "noneofurbiz\ " />\n" ; 
var cmdclose = "<closeConnection/>\n" ; 
xmlSocket . send ( cmdConnect ) ; 
xmlSocket . send (cmdLogin) ; 
xmlSocket. send (cmdclose) ; 



And in ActionScript: 




private function onConnect (evt: Event ): void { 
var cmdConnect : String = "<connect/> \n"; 
var cmdLogin: String = 

"<login username=\ " ivan\ " password=\ "noneofurbiz\ " />\n" ; 
var cmdclose: String = "<closeConnection/>\n" ; 
xmlSocket . send ( cmdConnect ) ; 
xmlSocket . send (cmdLogin) ; 
xmlSocket. send (cmdclose) ; 



When the AIR app runs, the following output is generated by the server: 

»»>» Starting ReallySimpleServer - the Server to the Masses .. .Really ! 

Hey ya - talk to me. When you are done, send me a <closeConnection/> to quit. 

Here's what you wrote: <connect/> 

Here's what you wrote: <login username="ivan" password="noneofurbiz" /> 
Here's what you wrote: <closeConnection/> 



Listings 12-2 and 12-3 show the full source code for this example. 
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Listing 12-2: Socklt2Me.html. 



DropBoo 



xml version=" 1 . 0 " encoding="utf-8" ?> 




<title>SockIt2Me</title> 
<script type="text/javascript" src="AIRAliases. js"x/script> 

<script type= "text/ javascript "> 
private var xmlSocket; 

function init ( ) { 

xmlSocket = new air.XMLSocket ( ) ; 

xmlSocket . addEventListener (air . Event .CONNECT, onConnect) ; 
xmlSocket . addEventListener (air . IOErrorEvent . IO_ERROR, onlOError) ; 
xmlSocket . connect ( " localhost " , 6101) ; 

) 



function onConnect (evt) { 

var cmdConnect = "<connect/> \n" ; 

var cmdLogin = "<login username=\ " ivan\ " password=\ "noneofurbiz\ " /> \n"; 
var cmdclose = "<closeConnection/>\n" ; 
xmlSocket . send ( cmdConnect ) ; 
xmlSocket . send (cmdLogin) ; 
xmlSocket . send (cmdclose) ; 



function onlOError (evt) { 
alert ( "Error: " + evt); 

) 

</script> 

</head> 

<body> 

<p>XMLSocket ' s Done Right !</p> 

</body> 

</html> 



Listing 12-3: Socklt2Me.mxml. 

<?xml version=" 1 . 0" encoding="utf -8 " ?> 

<mx:WindowedApplication xmlns :mx="http : / /www. adobe . com/2006 /mxml " 
layout=" absolute" applicationComplete="init ( ) "> 

<mx:Script> 
<! [CDATA [ 

import flash. events .* ; 
import flash.net .XMLSocket; 



(continued) 
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Listing 1 2-3 (continued) 

ate var xmlSocket :XMLSocket ; 

iuj.ic function init ( ) : void{ 
xmlSocket = new XMLSocket ( ) ; 

xmlSocket. addEventListener (Event . CONNECT, onConnect) ; 
xmlSocket . addEventListener ( IOErrorEvent . IO_ERROR , onlOError ) ; 
xmlSocket . connect ( " localhost " , 6101) ; 
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private function onConnect (evt : Event ): void { 
var cmdConnect: String = "<connect/> \n"; 

var cmdLogin: String = "<login username=\ " ivan\ " password=\ "noneofurbiz\ " /> 
\n" ; 

var cmdclose : String = "<closeConnection/>\n" ; 
xmlSocket . send ( cmdConnect ) ; 
xmlSocket . send (cmdLogin) ; 
xmlSocket. send (cmdclose) ; 

) 

private function onlOError (evt : IOErrorEvent) : void { 
trace ( "Error : " + evt); 

) 

]]> 

</mx:Script> 

</mx:WindowedApplication> 



Creating a "Server Push" 
Socket Connection 

In the previous section, I walk you through the process of establishing an XML 
socket connection to a server and sending information to it. However, in this 
section, I expand on this basic functionality and allow the server to push data 
to the AIR client application and have the AIR app handle the incoming data. 

The major advantage to server push is that it eliminates the need for multiple 
clients to continually poll the server to look for new information. Clients 
simply remain in listen mode and wait for the server to come to them. Your 
AIR app is thus easier to implement, and it lessens the load on the server. 

However, because a server push solution is driven and controlled by the 
server-side process, much of the development effort will be on the server 
side. (For example, the server will need to be multithreaded, devoting a 
thread for each client that connects to it.) 
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The server side part of the server push solution is beyond the scope of 
this book. However, to give you a kick start, you can download the Java 

'ushServer . class from www. dummies . com/go/adobeairf d and 
initial testing and experimenting with your AIR app. 

In this example, I show you how to create a status monitor for a fictional 
company that displays status info (OK or NOT OK) for its local branches 
when the server pushes that info to it. (I'm not sure what, exactly, the status 
refers to, but you can be sure that it's of national importance!) 

The connection to the server happens much in the same way as how I walk 
you through it in the "Making an XML Socket Connection" section, earlier in 
this chapter. However, you need to add a data event handler to handle the 
incoming data. 

This example focuses on Flex to take advantage of its data-binding capabili- 
ties. However, the same logic applies to an HTML app as well. 

To begin, you define a basic grid UI to display status info. The data grid is 
linked to an ArrayCollection object called cities: 

<mx:VBox> 

<mx:DataGrid width="100%" height="100%" dataProvider=" {cities} "> 
<mx:columns> 
<mx:Array> 

<mx:DataGridColumn headerText="Test ID" dataField=" id" /> 
<mx:DataGridColumn headerText="City" dataField="city" /> 
<mx:DataGridColumn headerText= "Time" dataField="time" /> 
<mx:DataGridColumn headerText=" Status" dataField= " status " /> 
</mx:Array> 
</mx: columns> 
</mx:DataGrid> 
</mx:VBox> 

Next, you add the initial code: 

private var xmlSocket rXMLSocket ; 

[Bindable] private var cities : ArrayCollection = new ArrayCollection)); 
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private function init():void { 
connectToServer ( ) ; 

} 

private function connectToServer (): void { 
xmlSocket = new XMLSocket ( ) ; 

xmlSocket . addEventListener (Event .CONNECT, onConnect) ; 
xmlSocket . addEventListener (IOErrorEvent . IO_ERROR, onConnectError) ; 
xmlSocket . addEventListener (DataEvent .DATA, onDataReceived) ; 
xmlSocket .connect ( "localhost" , 6102) ; 

} 
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You then 



The citiesCollection array is created as bindable. The init ( ) function 
is called when the page loads. It calls the connectToServer ( ) function to 
the XML socket connection to the server. 



You then add handlers for the connect and io_error events. Here's the 
ActionScript code: 



private function onConnect (evt : Event ): void { 
subscribe ( "Denver" ) ; 
subscribe ( " Seattle " ) ; 
subscribe ( "Boston" ) ; 



private function subscribe (cityName : String) : void { 

var cmd:String = "<subscribe event=\"" + cityName + "\"/>\n"; 
xmlSocket . send (cmd) ; 

} 



private function onlOError ( evt : IOErrorEvent ) : void { 



mx. controls .Alert . show ( "Error. Unable to connect to server." ); 

} 















The onConnect ( ) handler is called when a connection is established. It 
calls the subscribe ( ) function, which sends an XML fragment to the server 
using send ( ) . 



The key event handler for dealing with server push is defined as onData 
Received ( ) : 



public function onDataReceived (evt :DataEvent) : void { 
var xml:XML = new XML (evt .data) ; 
var element : String = xml .name (). toString () ; 



if (element == "city") { 

var obj:Object = new Object!); 
obj.id = nextld++; 
obj.city = xml.Oname; 
obj.time = xml .property . Otime; 
ob j . status =xml . property . Sstatus ; 
cities .addltemfobj ) ; 

) 

} 



This function is called each time data is pushed from the server in the XML 
socket. In this simple example, you need to account only for city elements, 
but a real-world app could account for many different messages from the 
server by testing the value of the incoming element. 

When a city element is received, the XML structure looks like the following: 
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<city name= " Denver " > 

roperty time="12/01/2008 11:20:12PM" status="OK"/> 



The values from the XML document are then placed into an object, which is 
added to the cities array. 

The final task is to close the connection with the server when the app closes. 
To do so, you add a listener for the exiting event: 

NativeApplication.nativeApplication.addEventListener (Event .EXITING, onAppExit) ; 

Here's the handler: 

private function onAppExit (evt : Event ): void { 
disconnectFromServer ( ) ; 

} 

private function disconnectFromServer (): void 
var cmd:String = "<closeConnection />\n"; 
xmlSocket . send (cmd) ; 

) 

The disconnectFromServer ( ) function sends a <closeConnection/> 
element to the server, telling it to close the socket connection and end the 
conversation. 

Figure 12-1 shows the AIR client with data provided from the server. 




Figure 12-1: 

Data pushed 
from the 
server. 



Test ID 


City 


Time 


Status 


0 


Boston 


Mon Sep OB 22:35:2B EDT 200B 


OK 




l 


Denver 


Mon Sep OB 22:35:37 EDT 2008 


OK 




2 


Boston 


Mon Sep 08 22:35:40 EDT 2008 


OK 




3 


Denver 


Mon Sep 08 22:35:43 EDT 200B 


OK 




4 


Seattle 


Mon Sep 08 22:35:46 EDT 2008 


OK 




5 


Seattle 


Mon Sep 08 22:35:52 EDT 2008 


OK 




6 


Boston 


Mon Sep 0B 22:35:55 EDT 200B 


OK 




7 


Denver 


Mon Sep 0B 22:36:D1 EDT 2008 


OK 




B 


Boston 


Mon Sep 08 22:36:04 EDT 2008 


OK 




9 


Denver 


Mon Sep 08 22:36:13 EDT 200B 


OK 




10 


Denver 


Mon Sep 08 22:36:16 EDT 2008 


OK 




11 


Seattle 


Mon Sep 08 22:36:26 EDT 2008 


OK 




12 


Boston 


Mon Sep 08 22:36:37 EDT 2008 


OK 


- 
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Listing 12-4 shows the full source code for this section's example app. 
2-4: TwoSocks.mxml. 



<?xml version= " 1 . 0 " encoding="utf -8 " ?> 
<mx:WindowedApplication xmlns :mx="http : / /www. adobe . com/2006 /mxml" 
layout= "vertical " 
applicationComplete=" init ( ) "> 

<mx:Script> 
<! [CDATA [ 

import mx. controls .Alert ; 

import mx. collections . ArrayCollect ion; 

private var xmlSocket :XMLSocket; 
private var nextld:int; 

[Bindable] private var cities : ArrayCollection = new ArrayCollection ( ) ; 



private function init():void { 
connectToServer ( ) ; 

Nat iveApplicat ion. nativeApplication.addEventListener (Event .EXITING, 
onAppExit) ; 

) 

private function onAppExit (evt :Event) :void { 
disconnectFromServer ( ) ; 

) 

private function connectToServer (): void { 
xmlSocket = new XMLSocket ( ) ; 

xmlSocket. addEventListener ( Event. CONNECT, onConnect) ; 
xmlSocket . addEventListener (DataEvent .DATA, onDataReceived) ; 
xmlSocket. addEventListener (IOErrorEvent . IO_ERROR, onlOError) ; 
xmlSocket . connect ( " localhost " , 6102 ) ; 

} 



private function onlOError) evt: IOErrorEvent ): void { 

mx. controls. Alert. show ( "Error. Unable to connect to server." ) ; 

} 

private function subscribe (cityName : String) : void { 

var cmd:String = "<subscribe event=\"" + cityName + "\"/>\n"; 
xmlSocket . send (cmd) ; 

) 

public function onDataReceived (evt : DataEvent ): void { 
var xml:XML = new XML (evt .data) ; 
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var element : String = xml .name ( ) . toString ( ) ; 

if (element == "response") { 
//do something 

) 

else if (element == "city") { 
var obj:Object = new Object)); 
obj.id = nextld++; 
obj.city = xml.Sname; 
obj.time = xml .property . @value; 
obj .status =xml. property. @status; 
cities .addItem(obj ) ; 

} 



private function onConnect (evt : Event ): void { 
subscribe ( "Denver" ) ; 
subscribe ( "Seattle" ) ; 
subscribe ( "Boston" ) ; 

} 



private function disconnectFromServer ( ) : void { 
var cmd:String = "<closeConnection />\n"; 
xmlSocket . send (cmd) ; 

) 

]]> 

</mx:Script> 



<mx : VBox> 

<mx:DataGrid width="100%" height="100%" dataProvider=" {cities} "> 
<mx:columns> 
<mx:Array> 

<mx:DataGridColumn headerText="Test ID" dataField=" id" /> 
<mx:DataGridColumn headerText="City" dataField="city" /> 
<mx:DataGridColumn headerText="Time" dataField="time" /> 
<mx:DataGridColumn headerText=" Status" dataField= " status " /> 
</mx:Array> 
</mx: columns> 
</mx:DataGrid> 
</mx:VBox> 



</mx:WindowedApplication> 
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In This Chapter 

Playing sounds 
Adding sound effects 
Accessing the microphone 




MyMy hether you want to create a full-fledged media player or simply add 
ww sound effects, you can include AIR's sound capabilities inside your 
application. 

Adobe AIR allows you to take advantage of Flash's capabilities to work with 
audio inside your apps. What's more, AIR enables you to connect with and 
use a computer's microphone. 

In this chapter, I take you into the world of audio. No longer will your AIR 
apps be forced into library-like silence. Instead, you can discover how to add 
sounds to respond to events in your apps. I also walk you through how to 
work with a microphone. 



Adobe AIR allows you to work with sound files in your app through the 
Sound class. Each instance of Sound is used for playing a specific sound file 
inside your app directory, local file, or a network resource. However, several 
related classes can also act upon these sounds. Table 13-1 lists these classes. 



Working With Sounds 
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Sound-Related Classes 



dBooM 



Description 



. ] Sound 



Manages basic sound load and playback. 



[air . ] SoundChannel 



Controls the playback of a particular Sound 
instance, including the volume of left/right 
channels. Each Sound instance has a 
companion SoundChannel. 



[air . ] SoundMixer 



Manages the playback and security properties 
to all sounds in an app. 



[air . ] SoundTransf orm 



Controls volume and panning for a specific 
SoundChannel, the SoundMixer object, orthe 
Microphone object. 



[air . ] 

SoundLoaderContext 


Manages buffering time and policy 
permissions during sound loading. 




[air. ] Microphone 


Controls the computer microphone 
audio stream properties. 


and its 



[air. ] ID3lnfo 



Provides access to the ID3 metadata of an 
MP3 file. 



Playinq a sound file 

If you're simply playing a sound file, you just need to create a Sound 
instance, load the URL, and then play it. Here's how it looks using JavaScript: 



function playSoundO { 

var soundFile = new air .URLRequest 
( " app : /assets /iphone .mp3 " ) ; 
var snd = new air . Sound () ; 
snd. load(soundFile) ; 
snd. play ( ) ; 



Or, in ActionScript: 

private function playSoundO :void { 

var soundFile : URLRequest = new URLRequest 

( "app : /assets / iphone .mp3 " ) ; 
var snd: Sound = new Sound () ; 
snd. load(soundFile) ; 
snd. play ( ) ; 
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In this example, the snd instance of Sound loads the sound file referenced by 
soundFile. After it's loaded, it's played using play ( ) . 



pie is fine for small or local sound files, but you typically want to 
account for possible delays in the loading process before you attempt to 
play a sound back. Therefore, it's good practice to add an event listener to 
the [air . ] Event . complete event to start playback after the resource has 
been loaded. Note the bolded lines of JavaScript code, which connect the 
event listener: 



function playSoundO { 

var soundFile = new air .URLRequest 

( "app : /assets / iphone .mp3 " ) ; 
var snd = new air . Sound () ; 
snd . addEventLi st ener ( air . Event . 

COMPLETE, onSoundLoaded) ; 
snd. load (soundFile) ; 



function onSoundLoaded ( event ) { 
loadedSound = event . target ; 
loadedSound.play ( ) ; 

} 



Here's the ActionScript version: 



private function playSoundO :void { 

var soundFile : URLRequest = new URLRequest ( "app: /assets/ 

iphone .mp3 " ) ; 
var snd: Sound = new Sound (); 

snd. addEventListener (Event. COMPLETE, onSoundLoaded) ; 

snd. load (soundFile) ; 



private function onSoundLoaded ( event ) :void { 
var loadedSound : Sound = event. target as Sound; 
loadedSound.play ( ) ; 

} 



What's more, if you're loading a large audio file from the Web, you can use 
the [air . ] ProgressEvent . PROGRESS to monitor and display the prog- 
ress of the loading process. When you trap for this event, you can access the 
bytesLoaded and bytesTotal properties of the event. 

As always, you should also trap for loading errors by listening to the [air . ] 
IOErrorEvent . IO_Error. 
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Here's an updated version of the sound-playing example with these two event 
handlers. Note that the new event handlers are shown in bold. The JavaScript 
hown first. 

.on playSound ( ) { 
var soundFile = new air .URLRequest ( "http: //www. 

richwagnerwords . com/really-long .mp3 " ) ; 
var snd = new air . Sound () ; 

snd. addEventListener (air . Event . COMPLETE, onSoundLoaded) ; 
snd . addEventListener ( air . Progres sEvent . PROGRESS , 

onLoadProgress) ; 
snd . addEventListener ( air . IOErrorEvent . IO_ERROR, 

onLoadError) ; 
snd. load(soundFile) ; 

} 

function onSoundLoaded (event) { 
loadedSound = event . target ; 
loadedSound.play ( ) ; 

} 

function onLoadProgress (event) { 

var myText = event .bytesLoaded + " of " + event. 
bytesTotal " loaded."; 

} 

function onLoadError ( event ) { 

alert ( "The request sound file could not be loaded. But 
thanks for trying ! " ) ; 

} 

And here's the ActionScript code: 

private function playSound () :void { 

var soundFile : URLRequest = new URLRequest 

( "app : /assets/iphone .mp3 " ) ; 
var snd: Sound = new Sound (); 

snd. addEventListener (Event . COMPLETE, onSoundLoaded) ; 
snd . addEventListener ( Progres sEvent . PROGRESS , 

onLoadProgress) ; 
snd . addEventListener ( IOErrorEvent . IO_ERROR, 

onLoadError) ; 
snd. load (soundFile) ; 

} 

private function onSoundLoaded ( event ): void { 

var loadedSound: Sound = event. target as Sound; 
loadedSound.play ( ) ; 

} 

private function onLoadProgress (event : Progres sEvent) : 
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void { 

statusUpdate . text = String ( event . bytesLoaded ) + " of 
+ String( event .bytesTotal) + " loaded."; 



private function onLoadError ( event : IOErrorEvent ): void { 

alert ( "The request sound file could not be loaded. But 
thanks for trying ! " ) ; 

} 



Pausing and resuming playback 

Although the play ( ) method is sufficient for working with short sound 
effects or clips, you probably want to allow users to pause or stop the play- 
back of longer audio files. To do so, use the SoundChannel object (which is 
assigned to every Sound object) to provide this additional layer of control. 
This section shows you how to set up this functionality. 

Begin by declaring the Sound variable and creating the instance inside the 
init ( ) function. You need to refer to its accompanying SoundChannel 
object, so you can declare that now as well. The JavaScript code looks like 
this: 

var snd; 

var SoundChannel; 

function init() { 

snd = new air . Sound (new air .URLRequest ( "app: /assets/you- 
could-be-happy .mp3 " ) ) ; 

} 

Or, in ActionScript: 

private var snd : Sound; 

private var SoundChannel : SoundChannel ; 

private function init():void { 

snd = new Sound(new URLRequest (" app : /assets /you-could- 
be-happy.mp3 " ) ) ; 

} 

The sound file is ready to roll when you're ready to play it. 

The key to creating pause/resume functionality is the ability to track the 
current position of the playback as it plays. You use the position property 
of the SoundChannel for this purpose. You can use the variable playback 
Position to store the latest position. 
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Here's the code in JavaScript: 

[aybackPosition = 0 ; 

.ctionScript: 

var playbackPosition : int = 0 ; 

Then, when you play the sound file, you want to use playbackPosition as 
the startTime parameter for play ( ) . Here's the JavaScript: 



function playSong ( ) { 

soundChannel = snd. play (playbackPosition) ; 

} 



Or, in ActionScript: 




private function playSong (): void { 

soundChannel = snd. play (playbackPosition) ; 

} 




To pause playback, you use the stop ( ) method of the SoundChannel. 
However, before doing so, you capture the current playback position: 

Here's the code in JavaScript: 


function pauseSong ( ) { 

playbackPosition = soundChannel 
soundChannel . stop ( ) ; 

} 


.position; 









And in ActionScript: 



private function pauseSong () : void { 

playbackPosition = soundChannel .position; 
soundChannel . stop ( ) ; 

} 

The entire JavaScript code is as follows: 

var snd; 

var soundChannel; 
var playbackPosition = 0; 
// Called on document load 
function init ( ) { 

snd = new air . Sound (new air .URLRequest ( "app: /assets/you- 
could-be-happy .mp3 " ) ) ; 

} 

function playSong ( ) { 
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soundChannel = snd.play(playbackPosition) 
on pauseSong ( ) { 

backPosition = soundChannel .position; 
oundChannel . stop ( ) ; 



Not to be forgotten is the ActionScript code: 

import flash . events . Event ; 
import flash . media . Sound; 
import flash . media . SoundChannel ; 

private var snd: Sound; 

private var soundChannel : SoundChannel ; 
private var playbackPosition : int = 0; 



// Called when application loading is complete 
private function init():void { 

snd = new Sound(new URLReguest ( "app: /as sets/you- could- 
be-happy .mp3 " ) ) ; 

} 



private function playSong ( ) : void { 

soundChannel = snd. play (playbackPosition) ; 

} 

private function pauseSong () :void { 

playbackPosition = soundChannel .position; 
soundChannel . stop ( ) ; 

} 



Adding sound effects 

You can use the SoundTransf orm class to control volume and panning (the 
relative balance between left and right speakers) of a sound channel. Using 
SoundTransf orm on a channel can give you some interesting effects. Here's 
an example of using SoundTransf orm to create a swirl-like effect across the 
speakers as the sound file plays. 

You begin by declaring Sound, SoundChannel, and SoundTransf orm vari- 
ables. You also declare a counter variable, which I use in the example. Here's 
the code in JavaScript: 

var snd; 

var counter = 0; 
var channel; 

var transf ormer SoundTransf orm; 
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And here's the code in ActionScript: 

^\ ^3 A^4^"^t e var sn d : Sound; 
J f | J I J fj 111 jEr^yEEfce var counter : Number = 0 ; 

privSte var channel : SoundChannel ; 
private var transformer : SoundTransf orm; 

A playSound ( ) function begins by loading the file. 

Use this code in JavaScript: 

function playSound () { 

var soundFile = new air .URLRequest ( "app: /assets/ 

iphone .mp3 " ) ; 
var snd = new air . Sound () ; 
snd. load (soundFile) ; 



Or, in ActionScript: 



private function playSound () :void 
var soundFile : URLRequest = new I 

iphone .mp3 " ) ; 
var snd: Sound = new Sound (); 
snd. load (soundFile) ; 


{ 

JRLRequest ( " app : 


/assets/ 


} 









After the sound file is loaded, you need to create a new SoundTransf orm 
instance. The first parameter specifies the volume level and the second speci- 
fies the panning (-1.0 is all left, 1.0 is all right, 0 is a balance). The play ( ) 
method uses the SoundTransf orm instance. One last task: You need to 
attach event handlers to the SoundChannel complete event and enter_ 
frame events. Here's the JavaScript code: 



transformer = new SoundTransf orm ( 0 . 5 , 


1.0); 


channel = snd. play (0, 1, transformer) 




channel . addEventListener (Event . SOUND_ 


COMPLETE , 


onPlaybackComplete) ; 




channel . addEventListener ( Event . ENTER_ 


FRAME, 


onEnter Frame) ; 





The full ActionScript function looks like this: 



private function playSoundO :void { 

var soundFile : URLRequest = new URLRequest ( "app: /assets/ 

iphone .mp3 " ) ; 
var snd: Sound = new SoundO; 
snd. load(soundFile) ; 

transformer = new SoundTransf orm ( 0 . 5 , 1.0); 
channel = snd.play(0, 1, transformer); 
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channel . addEventListener (Event . SOUND_COMPLETE , 
onPlaybackComplete) ; 
nel . addEventListener (Event . ENTER_FRAME, 
onEnter Frame) ; 



The event handlers for the SoundChannel events are as follows, beginning 
with the JavaScript: 



function onEnterFrame (event) { 

transformer .pan = Math . sin (counter ) ; 
channel . soundTrans form = transformer; 
counter += 0.05; 

} 



function onPlaybackComplete (event) { 

removeEventListener ( air . Event . ENTER_FRAME , 
onEnterFrame) ; 

} 



Now for the ActionScript code: 



private function onEnterFrame (event : Event ): void { 
transformer .pan = Math. sin (counter) ; 
channel . soundTrans form = transformer; 
counter += 0.05; 



private function onPlaybackComplete (event : Event) : void { 

removeEventListener (Event . ENTER_FRAME, onEnterFrame) ; 

} 



Mike Me Up: Working 
With the Microphone 

Adobe AIR enables access to the microphone or other input device of a com- 
puter. Here's an example of accessing the microphone and adjusting several 
of the sound properties. In JavaScript, use this code: 

var mic = air .Microphone . getMicrophone () ; 

mic . setUseEchoSuppression (true) ; 
mic . setLoopBack ( true) ; 
mic. gain = 30; 
mic. rate = 11; 
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Here's the ActionScript equivalent: 

c : Microphone = Microphone . getMicrophone () ; 



etUseEchoSuppression ( true) ; 
mic . setLoopBack ( true) ; 
mic.gain = 3 0; 
mic. rate = 11; 

Of special note, the setLoopBack ( true ) method sends incoming audio to 
the local speakers. 



Chapter 14 

and Easy: Instant 
Downloading and 
Auto-Updating 

In This Chapter 

Using badge . swf for easy downloads of your app 
Adding auto-update functionality to your app 



Xome of the best aspects of normal Web applications are that installation 

and maintenance issues are a breeze to deal with. Because the app 
resides on a server you control, you simply copy a new version of the app, 
and all the users accessing it from their browser instantly receive the latest 
version. 

Not so with traditional desktop apps. Because the app exists on hundreds, 
if not thousands, of computers, the issues of installation and app updates 
become quite problematic. 

Fortunately, Adobe thought about this problem in the construction of Adobe 
AIR. In fact, AIR offers point-and-click install and no-hassle updates as two 
built-in capabilities of Adobe AIR that AIR developers can take advantage of. 
In this chapter, I walk you through how to add these capabilities to your app, 
putting on that finishing touch that makes your app usable and professional 
looking. 
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Seamlessly Installing an 
DropB©0^6^/tA badqe.srtf 

The AIR SDK comes with the badge . swf file (located in the samples /badge 
subdirectory) that enables you to provide a seamless installation of your app 
from a Web page. The benefits of using the badge . swf file are as follows: 

The badge . swf installer checks to see whether the AIR runtime is 
installed. If the AIR runtime isn't detected, the runtime is automatically 
installed prior to installation of your app. 

v 0 The user has a choice of whether to install the AIR app without saving 
the . air file onto his or her computer. 

v 0 You can easily customize the graphic, badge color, and button color 
by setting parameters. You can even customize the badge . swf source 
code to give the badge a personalized look and feel. 

W Using badge . swf provides a seamless, friendly installation experience 
for your users that will make them smile uncontrollably at their computer 
monitor. 

To set up the badge . swf file for your AIR app, follow these steps: 

Locate three files in your samples /badge subdirectory of the AIR 
SDK: badge . swf , AC_RunActiveContent . j s , and default_ 
badge . html. 

You'll copy these files up to your Web server in a moment. 

Open def ault_badge . html in your HTML editor. 

The def ault_badge .html file contains boilerplate code for including 
the "install badge" (the Flash-based installer) on a Web page. 

You can customize the def ault_badge .html page to use it on your 
Web site. Or, more likely, you'll want to simply copy and paste the 
install badge code into your existing Web page. 

Locate the AC_FL_RunContent ( ) function call in the JavaScript code. 

It's the one with a bunch of parameters inside its parentheses. 
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4. Customize the f lashvars parameter (the string parameter that fol- 
lows ' f lashvars '). 

have three required parameters to update: 

appname: Enter the name of your application that you want to be 
displayed in a message under the Install button (shown only if the 
AIR runtime is not present). 

These parameters need to be escaped, so use a %20 in place of a 
space in your app's name. For example, AIR Mate is 

AIR%2 0Mate 

• appurl: Enter the full (not relative) URL of the . air file. 

• airversion: If necessary, update the version of the AIR runtime 
required for your app. 

In addition, you may want to customize three optional parameters: 

• imageurl: Indicates the URL of the . jpg file to display in the 
badge interface. 

• buttoncolor: Specifies a hex color value for the button back- 
ground. 

• messagecolor: Provides a hex color value for the color of the text 
message displayed under the Install button. 

Here's an example: 

' appname=AIR%2 0Mate&appurl=http : / /www. dummies . com/ air/ 
airmate . air&airversion=l . 0&imageurl=test . jpg ' 

5. If needed, adjust the width and height parameters of the ac_fl_ 
RunContent ( ) function call. 

The badge . swf needs a minimum size of 217 x 180 pixels. If you need to 
make it bigger, then adjust. 

6. Save the HTML file or copy and paste the source code to another Web 
page. 

7. Upload the badge . swf, AC_RunActiveContent . j s, and def ault_ 
badge . html files (or your own Web page) to your Web server. 

Figure 14-1 shows the customized badge displayed for my AIR app. 
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A ^ O Adobe AIR Application Installer Page 

| * | *• ) I {5 | | C | | _i | |rXi| | x-"' | | 1P | A http://www.richwagnerwords.com/air/Pefault_Pad9e.l1tm 
Application Inst. 



Figure 14-1: 

The badge 
. swf 
displayed 
on a Web 
page. 



When the badge is clicked by the user, helper text is displayed that indi- 
cates to the user what to do next to begin the installation. See Figure 14-2 for 
details. 




Figure 14-2: 

When 
clicked, 
the badge 
informs the 
user of the 
download 
action. 



J 
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If clicked again, the installation process begins (see Figures 14-3 and 14-4). 
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Application Install 



Figure 14-3: 

Application 
Setup dialog 
box. 



Are you sure you want to install this 
application to your computer? 



Publisher: 
Application: 
System Access: 



Installing applications may present a security risk to you and your 
computer. Install only from sources that you trust. 

(x) Publisher Identity. UNKNOWN 

The publisher of this application cannot be determined. 

x System Access: UNRESTRICTED 

This application may access your file system and the internet, 
which may put your computer at risk. 



Figure 14-4: 

User has 
the option 
of saving 
or opening 
without 
saving. 



ft n O Application Install 



Would you like to open or save this file? 



Flic: AIRWrite-air 
Type: Application 
From: www^kh 




Cancel Save Open 




The AIR SDK also includes the source files for the badge . swf file. These files 
are included in the src folder of the SDK. The badge . f la is the source Flash 
CS3 file, and AiRBadge . as is an ActionScript 3.0 class that defines the base 
class used in badge . f la. 



AutoMpdating \lour AlK Application 

As I mention at the start of this chapter, one of the major benefits of a Web 
app is that it's easy to update. Because users access it remotely, all the appli- 
cation code is located on the server. Therefore, when a bug is fixed or a new 
feature is introduced, a developer can seamlessly update the application 
code base without any user intervention. 
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By contrast, because desktop apps run off a locally installed file, versioning 
and performing updates have always been much more complicated tasks for 
applications. Fortunately, Adobe AIR comes with an auto-updating 
k that makes the task of updating your app a snap. In fact, after you 
integrate the update framework into your app, you receive several features 
for free: 



Checking for updates periodically based on a specific interval or user 
request 

Displaying version info to user 
C" Downloading an updated version and displaying Install dialog box 
Informing the user the first time the new version is being run 

To add these capabilities to your app, you need to do four tasks: 

1. Add the update framework to your app. 

2. Update the updater descriptor file for your app/version. 

3. Upload the descriptor file and updated . air file to your Web server. 

4. Add update framework code to your app. 

I describe these tasks in the following sections. 



Adding the A\R update (mmertork 

Before beginning the task of dealing with the specifics of your app, you need 
to add the AIR Update Framework to your application. To do so, follow these 
steps: 



1. Download the AIR Update Framework at http : / / labs . adobe . com/ 
wiki / index . php/Adobe_AIR_Update_Framework. 

At the time of writing, this framework was still in development and not 
considered part of the final SDK. 

2. After you download and decompress the framework, copy the folder 
to your AIR SDK directory so that you can have it on hand. 

3. Add the appropriate framework file to your project. 

For HTML apps, you'll want to reference either ApplicationUpdater . 
swf or ApplicationUpdater_Ul . swf . (The UI version includes addi- 
tional calls to display a UI for showing update and install options.) After 
copying the desired . swf file to your application directory, add the fol- 
lowing script element: 

<script src="applicationUpdater_UI . swf " type=" application/ 
x-shockwave-f lash" /> 
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For Flex apps, you want to use either ApplicationUpdate . swc or 
ApplicationUpdate_Ul . swc. (As with the . swf files mentioned pre- 
sly, the UI equivalent includes additional calls to display a UI for 
ing update and install options.) To do so, copy the . swc to the lib 
directory of your app or add its existing directory to your library path. 
You can then import the updater UI and event packages with the follow- 
ing declarations: 



import air .update . ApplicationUpdaterUI ; 
import air . update . events . UpdateEvent ; 

For most purposes, I recommend using the _ui versions of the framework 
files. You'll save yourself a lot of time. I'll focus on the UI versions in the 
remainder of this chapter. 



Creating the updater descriptor file 

The update framework uses an XML-based updater descriptor file to define 
the update versioning. An AIR app accesses this XML file from a Web server 
when it performs a version check, checking to see whether a new version has 
been uploaded. 

Here's a sample file: 

<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 
<update xmlns= "http : / /ns . adobe . com/air/ 

framework/update/description/ 1 . 0"> 
<version>2 . 0</version> 

<url>http : / /richwagnerwords . com/air/AIRUpdates . air</url> 
<description>< ! [CDATA [ 
AIRUpdates has an exciting new version for you. Version 
2 . 0 update includes : 

* Bug fixes 

* New UI 

] ]> 

</description> 
</update> 

The version element specifies the new version of the app. This value is 
compared to the version element in the application descriptor file. The 
url element indicates the location of the new . air file to download. The 
description element is optionally used to provide release notes and other 
info you want the user to see prior to installation. 



After you've updated this file, you want to upload it to the Web server. 
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have the update framework added to your AIR app project and 
ter descriptor file set, you're ready to add the updater to your 
application code. 

Creating an instance of ApplicationUpdaterUl 

You first want to create an instance of the ApplicationUpdaterUl object. 
In JavaScript, use 

var appUpdater = new ApplicationUpdaterUl () ; 

In ActionScript, use: 

private var appUpdater : ApplicationUpdaterUl = new 
ApplicationUpdaterUl ( ) ; 

Customizing the updater from code 

You can customize the settings of the updater by working with the 
properties of the ApplicationUpdaterUl instance. The properties are 
shown in Table 14-1. 



Table 14-1 


ApplicationUpdater and 




ApplicationUpdaterUl Settings 


Application 


XML Configuration Default Description 


UpdaterUI or 


File Element/Attribute 


Application 




Updater Property 





updateURL <urlx/url> Specifies the 

URL of the XML- 
based updater 
descriptor file 
that you create in 
the "Creating the 
updater descrip- 
tor file" section 

1 Specifies the 

interval (number 
of days) in which 
the app should 
checkfor an 
update 



delay <delay>< 
/delay> 
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Application 
ipdaterUI or 
i.tion 

wr Property 



XML Configuration 
File Element/Attribute 



Default Description 



isCheckFor 
UpdateVisible 



<defaultUI> 

<dialog name= 
" check 
ForUpdate" 
visible= " true 
| false " /> 

</defaultUI> 



true 



isDownload 
UpdateVisible 



<defaultUI> 

<dialog name= 
" downloadUp 
date" visible= 
" true | false " / > 

</defaultUI> 



islnstall 
UpdateVisible 



<defaultUI> 

<dialog name= 
" installUpdate" 
visible= " true 
| false " /> 

</defaultUI> 



true 



isDownload 

Progress 

Visible 



<defaultUI> 

<dialog name= 
" download 
Progress " 
visible= " true 
| false " /> 

</defaultUI> 



true 



isFile 

UpdateVisible 



<defaultUI> 

<dialog name= 
" f ileUpdate " 
visible= " true 
| false" /> 

</defaultUI> 



true 



Indicates 
whether the 
Check for Update, 
No Update, and 
Update Error 
dialog boxes are 
visible 



True Indicates 
whether the 
Download Update 
dialog box is 
visible 



Determines 
whether the 
Install Update 
dialog box is 
visible 



Specifies 
whether the 
Download 
Progress and 
Download Error 
dialog boxes are 
visible 



Determines 
whether the 
Install Update 
dialog box shows 



(continued) 
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Table 14-1 (continued) 


J W%D 111 nr 

Application 
Updater Property 


XML Configuration 

Filf* Flf*nit>nt/J\ttrihntt> 

1 lltr LI tr lilts III/ /111! IUU Its 


Default 


Description 


isUnexpected 
ErrorVisible 


<defaultui> 
<dialog name= 


true 


Indicates 
whether the 
Unexpected Error 
dialog box can be 
visible 




"unexpected 
Error" visible= 
" true | false " / > 

</defaultUI> 





The following code sets the URL, prompts the updater to check every half 
day, and hides the Check for Updates dialog box: 

appUpdater .updateURL = "http : //dummies . com/air /AIRUpdates_versions .xml" ; 
airUpdater. delay = 0.5; 

airUpdater . isCheckForUpdateVisible = false; 

Customizing the updater from an XML configuration file 

You can also configure the updater through an XML configuration file. Table 
14-1 shows the elements and attributes you can use in the markup. The fol- 
lowing file provides identical configuration as the earlier scripting code: 



<?xml version= " 1 . 0 " encoding= "utf -8 " ?> 




<conf iguration xmlns= "http : / /ns . adobe . com/air / framework/ 


update/conf iguration/1 . 0 " > 




<url>http : / /dummies . com/air /AIRUpdates_versions 


.xml</url> 




<delay>0 . 5</delay> 




<defaultUI> 




<dialog name="checkForUpdate" visible=" false" /> 


</defaultUI> 




</ conf iguration> 





To load the configuration file, add the following line to your app code: 



appUpdater . conf igurationFile = new [air .] File ( "update- 
conf ig . xml " ) ; 
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Initializing the ApplicationUpdaterUl instance 

The next step is to add event listeners to the updater and then initialize it. 



appUpdater . addEventListener ( [air . ] UpdateEvent . INITIALIZED, 
onUpdate) ; 

appUpdater . addEventListener ( [air. ] Err or Event . ERROR, 
onError) ; 

appUpdater . initialize ( ) ; 

You want to add this code to the init ( ) function that is executed when the 
application loads. 

Addinq ei/ent handlers 

Next, you need to add event handlers that will kick off when appUpdater is 
ready to check for an update or when an error occurs. Here's the JavaScript: 



function onUpdate (event) { 
/ / Add code here 

} 

private function onError (event) { 
alert ( event . toString ( ) ) ; 

} 



private function onUpdate (event : UpdateEvent ): void { 
/ / Add code here 

} 

private function onError (evt : ErrorEvent) : void { 
Alert . show ( evt . toString ( ) ) ; 

} 



Checking for updates 

Your final step is for the appUpdater instance to check for a new version 
using the checkNow ( ) method. You want to add this code to the onUpdate ( ) 
event handler: 




In ActionScript: 



appUpdater . checkNow ( ) ; 

Listings 14-1 and 14-2 provide full source code for an HTML and Flex app. 
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Listing 14-1: AIRUpdates.html 
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IRUpdates</title> 
<script type="text/javascript" src="AIRAliases . js" /> 
<script src="applicationUpdater_UI . swf " type="application/x-shockwave-f lash" /> 
<script type= "text/ javascript "> 



var appVersion:String; 
var file : File; 

var airFileURL : String = "http://richwagnerwords.com/air/AIRUpdates.air"; 



var appUpdater = new air.ApplicationUpdaterUIO ; 



function init ( ) { 
initAutoUpdate ( ) ; 

) 

function initAutoUpdate ( ) { 

appUpdater .updateURL = "http : / /richwagnerwords . com/air /AIRUpdates_ 
versions .xml" ; 

appUpdater . addEventListener (air .UpdateEvent . INITIALIZED, onUpdate) ; 
appUpdater . addEventListener (air .ErrorEvent . ERROR, onError) ; 
appUpdater . initialize ( ) ; 



function onError ( event ) { 
alert (event . toString ( ) ) ; 

) 

function onUpdate (event) { 
appUpdater . checkNow ( ) ; 

) 



</script> 
</head> 

<body onload="init ( ) " bgcolor="#0080C0"> 

<p>AIRUpdates</p> 

</body> 

</html> 



As you consider the Flex version, note that there is additional code that 
checks to see whether the app has been run before. If not, a welcome mes- 
sage is displayed. The updater process kicks in after this initial check. 
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Listing 14-2: AIRUpdates.mxml 



applicationComplete=" init ( ) "> 
<mx: Script> 
<! [CDATA [ 

import f lash. f ilesystem. * ; 

import mx. controls .Alert ; 

import flash. events .ErrorEvent; 

import air .update . Applicat ionUpdaterUI; 

import air .update . events .UpdateEvent; 

[Bindable] public var appVersion: String; 
public var file:File; 

private var airFileURL : String = "http://richwagnerwords.com/air/ 



private var appUpdater : ApplicationUpdaterUI = new ApplicationUpdaterUI ( ) ; 

public function init():void { 

var appDescriptor : XML = NativeApplication.nativeApplication. 

applicationDescriptor ; 
var ns:Namespace = appDescriptor .namespace () ; 
appVersion = appDescriptor .ns :: version; 
checkRunStatus ( ) ; 
initAutoUpdate ( ) ; 



private function initAutoUpdate (): void { 

appUpdater . updateURL = "http : / /richwagnerwords . com/air /AIRUpdates. 
versions .xml" ; 

appUpdater . addEventListener (UpdateEvent . INITIALIZED, onUpdate) ; 
appUpdater . addEventListener (ErrorEvent .ERROR, onError) ; 
appUpdater . initialize ( ) ; 



private function onError (evt : ErrorEvent ): void { 
Alert . show ( evt . toString ( ) ) ; 

) 

private function onUpdate (event : UpdateEvent ): void { 
appUpdater . checkNow ( ) ; 




'xml version=" 1 . 0 " encoding="utf-8" ?> 

H^t^rMowedApplication xmlns : mx= " http : / /www . adobe . com/2 0 0 6 /mxml 
layout= "vertical" title= "AIRUpdates" 



AIRUpdates . air" ; 



(continued) 
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Listing 14-2 (continued) 
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ivate function checkRunStatus ( ) : void { 
file = File . applicationStorageDirectory; 
file = f ile. resolvePath («Pref erences/vercheck. txt») ; 
if (file. exists) { 

checkAppVersion) ) ; 
} else { 

runFirstTime ( ) ; 

} 



private function checkAppVersion ( ) : void { 
var fs :FileStream = new FileStream) ) ; 
fs.open(file, FileMode.READ) ; 

var prevVersion: String = f s . readUTFBytes ( f s .bytesAvailable) ; 
f s . close ( ) ; 

var av:Number = Number (appVersion) ; 
var pv:Number = Number (prevVersion) ; 
if (av > pv) { 

Alert . show) «Welcome to the updated version of AIRUpdates, the coolest 

app in the biz.»); 
saveVersionToFile ( ) ; 

) 



private function runFirstTime (): void { 

Alert. show («Welcome to AIRUpdates, the coolest app in the biz.»); 
saveVersionToFile ( ) ; 

) 



private function saveVersionToFile (): void { 
var stream:FileStream = new FileStream( ) ; 
stream. openffile, FileMode .WRITE) ; 
stream. writeUTFBytes (appVersion) ; 
stream. close ( ) ; 

) 

]]> 

</mx:Script> 



<mx:VBox backgroundColor=»#6AA16A» x=»0» y=»0» width=»100%» height=»100%» 
horizontalAlign=»center» verticalAlign=»middle»> 
<mx:Label color=»white» text=»{appVersion}» f ontSize=»134»/> 
</mx:VBox> 



</mx:WindowedApplication> 



When the app runs, the updater kicks in. Because the isCheckForUpdate 
visible property defaults to true, the Check for Updates dialog box is 
displayed (see Figure 14-5). 
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Figure 14-5: 

Check for 
Updates 
dialog box. 



Updating: AIRUpdates 



Check for updates 



Allow the application to check for updates? 



Application: AIRUpdates 



When the Check for Updates button is clicked, the updater checks the server- 
based XML file. Because the remote file is for 2.0 and the current app is 1.0, 
the Update Available dialog box is displayed (see Figure 14-6). If the Release 
Notes text is clicked, the description content of the XML is displayed (see 
Figure 14-7). 
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Updating: AIRUpdates 



Update available 
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Figure 14-6: 

Update 
Available 
dialog box. 



Application: AIRUpdates 
Installed Version: 1.0 
Update Version: 2.0 



Download later 



Download now 
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Figure 14-8 shows the Download Progress dialog box. When the download is 
complete, the Install Update dialog box is displayed (Figure 14-9). 




Figure 14-8: 

Down- 
loading the 
update. 



Updating: AIRUpdates 



Download progress. 

Downloading update 



AIRUpdates has an exciting new version for you. 
Version 2.0 update Includes: 
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Updating: AIRUpdates 



Install update 

The update for the application Is downloaded and ready to be 



nstalled. 






Application: AIRUpdatM 
Installed Version: 1.0 
Update Version: 2.0 




Postpone until restart Install now 



Figure 14-9: 

Installing 
the update. 



AIRUpdates has an exciting new version for you. 
Version 2.0 update Includes: 
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In this part . . . 

■ f one is the loneliest number, ten is surely the "dumbest": 
«C the the Part of Tens section is a tradition in For 
Dummies books. This book therefore offers you a Part of 
Tens for "AIR-heads." In this part, you're privy to ten use- 
ful tips to help you with that oh-so-fun task of debugging 
your app. Also, if you're looking for AIR application exam- 
ples, you've come to the right place; here I present my 
choices for the ten best ones. 













Chapter 15 

0,3 Ten Tips for Successful 

AIR Debugging 



In This Chapter 

Adding ADL and Aptana Studio to your toolbox 
Using the alert command for quick and easy debugging 
Using the trace ( ) method for intelligent debug reporting 
Working with the AIR HTML Introspector 

••••••••••••••••••••••••••••••••••••••••••••••••a 

m ■ebugging is one of those necessary evils of application development. 
•*^It's never much fun but is essential to producing a quality, bug-free app. 
Adobe AIR provides various ways of debugging depending on the type of AIR 
application you're making. HTML-based apps can take advantage of the AIR 
HTML Introspector, which comes with the SDK. Flex Builder sports its own 
powerful debugger environment. Flash allows you to tap into the Adobe Flash 
Debugger. 

In this chapter, I introduce you to these powerful tools as well as other tips 
and techniques that you'll want to be sure to incorporate into your debugging 
process. 
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Use ADL (AlR Debug Launcher) 
OBm\£8trtin0 Point 



As I mention in Chapter 2, the AIR Debug Launcher (or ADL) is a command- 
line utility that comes with the Adobe AIR SDK. You can use ADL to test 
your apps without packing them up into an installable AIR app. Not only is 
it much quicker to test your app, but also any runtime errors that occur will 
be output to the ADL console window. Therefore, as you test your apps, con- 
sider ADL as your starting point for any debugging that you perform. 

To use ADL from the command line, be sure it is in your path and then enter 
the following at a prompt, where application . xml is your AIR application 
descriptor file: 



adl application . xml 



Better yet, if you're using Flex Builder or Aptana Studio, you can launch ADL 
directly through the IDE. See related tips later in this chapter for more details. 

ADL will run until your app closes. However, if your app freezes or you forgot 
to add a Close button to your app, simply close the command-line window. 



Make Aptana Studio \lour Home 
Base for HTML-Based Apps 

To be effective in your development and debugging processes, you need to 
be equipped with the right tools. If you're creating HTML/Ajax-based AIR 
apps, you need to check Aptana Studio. 

Aptana Studio is a full-featured integrated development environment (IDE) 
for Web developers. It offers an optional Adobe AIR plug-in that, when you 
install it, turns Aptana Studio into an IDE for Adobe AIR applications. 

Using Aptana Studio, you can quickly create AIR apps with its AIR Project 
Creation Wizard (shown in Figure 15-1), use AIR API-supported auto comple- 
tion in its source editor, and deploy final releases using its AIR package 
exporter (shown in Figure 15-2). However, what's most beneficial for debug- 
ging is that Aptana Studio frees you from the command line when working 
with ADL. It lets you run a test version of the app by clicking a toolbar button 
rather than typing everything at the command line (shown in Figure 15-3). 
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Figure 15-1: 

Creating a 
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project in 
Aptana 
Studio. 
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Figure 15-2: 

Package 
your app 
inside the 
Aptana 
Studio IDE. 



Adobe AIR Package Exporter 



Adobe AIR Package Contents 

Select the application and files to ir 



ude in (he Adobe A 



Certificate Password: 

Timestamp AIR Package 

Jaxer Options 

Deployed Web Address of Application: 



□ 


Li 








AIRAIiases.js 


□ 




AIRIntroSpector.js 




A 


AiRLocaiizer.js 


M 




AIRMenuBuilder.js 


Wl 




AIRSourcoViewer.jS 


M 




AIRWriteHtml.html 


Wl 


E 


Loca1File.txt 


& 


E 


application.xml 


M 






ffl 




V AIRApp_12B.png 



Project: AIRWriteHtm 




■** 




Application Descriptor application.xml 




m 








Adobe AIR SDK Default AIR SDK 


" — j"j Conflau 


e Adobe AIR. SDKs... 


Digital Signing 






iV Digitally sign exported AIR file 

Certificate: ' Aptana Default Certificate 




nfioure Certificates 



( Check All ) 
( UncheckAII ) 



/Users/rich/DeMelopment/airdev/HTML/AIRWriteHtml/AIRWr-teHtml.air 



306 Part IV: The Part of Tens 




Quick and East} bebuqqinq: 
Use the alert Command 



Sure, the alert command is usually considered the "poor man's debug- 
ger." Despite its clumsiness, it can be a handy quick and easy way to initially 
debug part of your application. 

In JavaScript, you use the ubiquitous window, alert ( ) method: 

alert ( "Yikes , a problem occurred."); 
In ActionScript, you call the Alert object's show ( ) method: 

import mx . contols .Alert ; 

Alert . show (( "Yikes , a problem occurred."); 
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on event r 

DropBoate 

was beine 



The alert command is particularly handy when you are doing initial testing 
on event handlers. In most cases, you will want to replace these alerts with 
histicated techniques before final deployment. Here's a handler for 
rror that lets you know whether something went awry when a file 
was being read: 




function onlOReadError (evt) { 

alert (" Something wacky happened. 
+ f ile . nativePath) ; 

} 



We are unable to open 



Although alert ( ) can be useful, I recommend using it in your code during 
initial development phases and stripping out the alert ( ) calls from your 
code as your app gets closer to being final. 



Better \/et: Use the trace ( ) 
Method Instead of alert ( ) 

The alert ( ) debugging method displays debug info in a message box, and 
the execution of the app is interrupted to show those details. Adobe AIR 
enables you to use an alternative method, the global method called trace ( ) , 
which enables you to output debugging info to the ADL console window. 
Here's the syntax: 

[air .] trace ( "This text will be output"); 

Any nonstring objects that you add to trace ( ) will automatically be con- 
verted to a string (its toString ( ) method is called for you) during the 
output. 

Here's a JavaScript example of using trace ( ) to output the error message 
that is generated during a SQLErrorEvent . error event : 

sql . addEventListener (air . SQLErrorEvent . ERROR, function 
error (event) { 
air . trace (event . error .message) ; 

sql . removeEventListener ( air . SQLErrorEvent . ERROR, error) ; 
}) ; 

The trace ( ) method offers two key advantages over "alert box debugging." 
First, one of the problems when using alert boxes to display debugging info 
is that the dialog box itself can get in the way of normal flow of events in the 
execution of the app. However, because trace ( ) doesn't require any user 
input, it never gets in the way of normal flow. Second, although debug alert 
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boxes will need to be cleaned out of application code before the app is final, 
you can leave trace ( ) commands in the code without the info ever being 




users when run outside of ADL. 



Create \lour OvOn bebuq Window 

Although the trace ( ) command is a great way to output debugging info, 
sometimes you may want to view debugging info outside the ADL console 
window. 

If you're developing an HTML/JavaScript-based AIR app, you use a div 



element inside your app for this task and toggle its visibility, depending on 
whether you're in debug mode. Follow these steps: 

1. Add the following div to the bottom of your HTML document: 




<div id="debugConsole"> 
</div> 






2. 


Add the following CSS rule to your stylesheet: 






div#debugConsole 
{ 

display: none; 

} 








3. 


You can add any additional formatting properties you want. 

In your JavaScript code, add a global variable that indicates whether 
you're in debug mode: 




var debugMode = false; 





4. Add a function that toggles visibility of the debug div: 



enableDebugMode (state) 
{ 

debugMode = state; 

d = document . getElementByld ( "debugConsole ") ; 

i f ( debugMode ) 

d . style . display = "block"; 
else 

d . style . display = "none"; 

} 
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5. Create a doDebug ( ) function that outputs any debugging data you 
specify into the debugConsole div: 



nc t i on debug ( ou tpu t ) 



i f ( debugMode ) 
{ 

d = document . getElementByld ( "debugConsole" ) ; 
d. appendChi Id ( document. createTextNode (output) ) ; 

} 

} 

To use the window, simply enable debug mode when your app loads. For 
example: 



function init ( ) 
{ 

enableDebugMode ( true) ; 

} 






Then, add the followii 


ig line of code to outpu 


t to the debug console: 


debug ("debug text you want to displa 


y" ) ; 















Outputtinq to a Loq File vOith AlRLoqqer 

AIRLogger is a handy utility available from the ear-f ung . us developer blog 
that enables you to create a log file for debugging your HTML-based AIR app. 



To enable this utility, all you need to do is add a downloadable script file 
called AIRLogger . j s to your HTML document. You can then write to the log 
file by using the following command: 

log .write ( "my debugging info"); 

The debugging info is output to a log file called application . log on your 
desktop. 

To download AIRLogger.js, go to: www . ear - f ung .us/wp-content/ 
uploads/2008/08/airloggerlO . js. 

For more general AIRLogger info, go to www. ear-f ung. us/ apps/ air logger. 
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bebug HTML-Based Apps ufith 
DropBkHlkfflML htrospector 

The AIR HTML Introspector is an interactive debugging utility that you can 
use to test your HTML-based AIR applications. The AIR HTML Introspector 
goes beyond the basic debugging output that you get with alert boxes, 
trace ( ) , your own homegrown debug console, or even AIRLogger. You can 
use the AIR HTML Introspector to navigate the UI and DOM, adjust JavaScript 
properties, and even access local files in the application root directory. 



To enable the AIR HTML Introspector, you need to include the 



AlRlntrospector . j s file in your HTML application source. 

You can find the AlRlntrospector . j s file in the frameworks ! 
tory of the Adobe AIR SDK. You should copy the JavaScript file to 
cation directory and then add the following code to every HTML i 
app that will be visible: 


subdirec- 
your appli- 
ile in your 


<script type=" text /javascript" sri 
script> 


:= " AIRIntrospect 


or . j s " ></ 


When the code is executed, a Console class is created and is accessible by 
calling air . Introspector . Console. 

The log ( ) method can be used to send objects to the Introspector: 


new file = new air. File! 
air . Introspector . Console 


) 


log (file) ; 









When that line is encountered, the AIR HTML Introspector is displayed, as 
shown in Figure 15-4. 




After the AIR HTML Introspector is shown, you may find yourself becom- 
ing like a kid in a candy store. You can access the current state of UI 
elements (see Figure 15-5) and DOM, view application assets, and view 
application source files. What's more, the XHR tab allows you to watch all 
XMLHttpRequest communications of the app. 

The AIR HTML Introspector is designed to work primarily with sandboxed 
content (HTML files in your application directory). However, you can use the 
Introspector with nonsandboxed content that is inside an iframe or frame. To 
enable the AIR HTML Introspector, both the parent and frame HTML files need 
to include the AlRlntrospector . js file. 
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Figure 15-4: 
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bebug With Flex Builder 

DBookSa 

tiD is a no- 



lready using Flex Builder to develop Adobe AIR applications, this 
tip is a no-brainer. However, if you have not checked out Flex Builder's IDE, I 
recommend doing so. Flex Builder provides a full-featured debugging environ- 
ment for your AIR apps, including breakpoints, the ability to step line-by-line 
through code, variable/object inspection, and so on. After you debug AIR 
apps inside Flex Builder (as shown in Figure 15-6), it becomes hard to want to 
ever leave its environment. 




Test on Multiple Platforms 

Because Adobe AIR apps work in Windows, Mac, and Linux, testing your 
application across multiple platforms is important. Although much of the 
functionality of your app will work as you designed, it could have some UI 
glitches or inconsistencies that you don't expect. Therefore, before your final 
release, at a minimum, do a sanity check on your app. 



View Source Code 

You can enable the source code of your app to be viewed by users of your 
application or by yourself in a deployed environment. For HTML apps, you 
want to add the following script element to your page header: 
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<script type=" text /javascript" src= "AIRSourceViewer . j s " /> 



pBocfe 



ing that JavaScript file, you have access to the air . SourceViewer 
bb'jectTou can access a SourceViewer instance through the getDef ault ( ) 
method and then view the source by calling the viewSource ( ) method. 
Here's the code: 



function viewAppSource ( ) { 

var SourceViewer = air . SourceViewer . getDef ault () ; 
SourceViewer .viewSource ( ) ; 

} 



You can exclude certain files or folders from the code that is displayed by 
specifying a conf igObj ect array as the parameter when calling viewS- 
ource ( ) . For example: 

function viewProtectedSource ( ) { 

var SourceViewer = air . SourceViewer . getDef ault () ; 
var conf igObj = { } ; 

conf igObj . exclude = ["supersensitive.html", "trade- 
secrets .html " , "TopSecret"] 
SourceViewer .viewSource (conf igObj ) ; 

} 
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Chapter 16 

DropBo fe S n KillerRWsto Expl 



In This Chapter 

Google Analytics Reporting Suite 
eBay Desktop 

AOL Music - Top 100 Videos 



twhirl and Snitter 

AgileAgenda 

RichFLV 

Snackr 

Snippely 

uvLayer 






^^ince the official release of the Adobe AIR SDK, hundreds of rich Internet 


t 


^^applications (RIAs) have been developed and released on the Web. Some 




ire new takes on desktop utilities 


and widgets. Some are parts of 


existing 


i 


tVeb apps. A few are even full-scale commercial apps. 





Rather than show you the ten most useful RIAs, I use this chapter to highlight 
ten killer examples that demonstrate the power and flexibility of the AIR plat- 
form. Consider these ten to be inspiration for the type of applications that 
you can develop using Adobe AIR. 




One of the most beneficial aspects of surveying these RIAs is that they help 
you see how you can take a Web app that you've been working with online 
for years — such as eBay or Google Analytics — and seeing how AIR offers an 
entirely new take on how to tackle its respective problem domain. 
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Pure Usefulness: Google Analytics 
DropSpak^ Suite 



www . aboutnico . be 

Google Analytics is one of the most popular Web site traffic analysis tools 
available. The Google Analytics Reporting Suite takes much of the functional- 
ity of what Google offers on its Web site and packages it into a well-designed, 
visually attractive, and very responsive AIR application (see Figure 16-1). 



Figure 16-1: 

Google 
Analytics. 
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The Google Analytics Reporting Suite is an ideal desktop-based monitoring 
tool for Web site owners and administrators, eliminating the need to have a 
browser open to www. google . com/analytics. The application, written in 
Flex, makes effective use of charts, tabs, tabular lists, and a variety of other 
UI elements. You can also export data to PDF, Excel, or XML format. 




One of the smart moves that its developer Nicholas Lierman made was to lay 
out and organize the UI in a format complementary to the Google Analytics 
Web site, thereby making the transition to the AIR app a no-brainer for exist- 
ing Web app users. If you're porting an app from the Web to AIR, check out 
what Nicholas did. 
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You can read an article about the development of this app by its developer at 
the following URL: www. adobe . com/devnet/ air/ flex/ articles/ 
^jr|c^^jcs_r£port: ing_sui te_print .html. 



Pure Porter: eBay Desktop 

http : / / desktop . ebay . com 

eBay Desktop may well be the poster child demonstrating the power of 
Adobe AIR. Inside of its desktop UI, it packs a huge amount of features for 
searching, bidding, watching, and buying items on eBay (see Figure 16-2). 
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Figure 16-2: 

eBay 
Desktop 
packs a true 
AIR punch. 
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If you've bid on an item before at the end of the auction, you've probably 
found yourself constantly hitting the browser Refresh button to see the latest 
bid. eBay Desktop eliminates that hassle because it offers live updating of 
bids in the main auction screen. 
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However, perhaps the most impressive part of eBay Desktop is how it trans- 
forms searching for items. Because the UI can be more sophisticated than the 
HTML version on the Web site, the AIR app delivers an intuitive and 
ay to search for items and drill down for products inside categories 
and subcategories. 




The app was built using Adobe Flex. You can view a case study of the app at 
www. adobe . com/cfusion/showcase/index. cfm?event=casestudyde 
tail&casestudyid=3 83 833. 



Innovative Use of Media: AOL Music — 
Top 100 Videos 

http : / / music . aol . com/help/syndication/desktop-widgets 

AOL's entry into the AIR world is AOL Music — Top 100 Videos, a stylish 
media player for browsing (see Figure 16-3), playing (see Figure 16-4), shar- 
ing, bookmarking, and rating popular music videos. Top 100 Videos provides 
a great example of how you can combine the slickness and savvy of a Flash- 
based UI with the speedy performance of a desktop app. 



Figure 16-3: 

Top 100 
Videos 
makes 
browsing 
for videos 
easy. 
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Figure 16-4: 

Integrated 
video player 
provided 
for playing 
videos. 



Top 100 Videos also shows you how to toggle between normal, full-screen, 
and side Dock views with an AIR app. 



Web App Upgrades: Whirl and Snitter 

www . twhir 1 . org 

http:// snook. ca/snitter 

Some Web apps are used so frequently throughout the day that you don't 
want to have a browser open to work with them. Twitter is one such exam- 
ple. For the uninitiated, Twitter is a social-networking app in which you can 
communicate quick messages to friends and colleagues. Rather than con- 
stantly refresh your Twitter page, you can use either of these two Twitter cli- 
ents: twhirl (see Figure 16-5) and Snitter (see Figure 16-6). 

Both encapsulate the functionality of Twitter for the desktop and do what a 
desktop client can do best — be instantly available when you need it. 

The full-featured functionality of twhirl (which was built using Flex) goes 
beyond basic emulation. It allows you to connect to Twitter using multiple 
accounts, cross-post to Pownce and Jaiku, and post images to TwitPic. You 
can also follow other users and search tweets using the tweenScan and ter- 
raminds Web services. 
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Figure 16-5: 

twhirl is a 
full-featured 



desktop 
Twitter 
client. 
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Figure 16-6: 

Snitter 
also brings 
Twitter 
functionality 
to the 
desktop. 




Business Use: AqileAqenda 

www . agileagenda . com 



I include AgileAgenda in this chapter because it's a good example of a 
real-world, business-oriented AIR application. AgileAgenda is a project 
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scheduling and management system (shown in Figure 16-7) that enables you 
to manage tasks, milestones, resources, and schedule. One of the advantages 
genda over a pure Web app is its ability to store project data either 
remotely on AgileAgenda's Web service. 



Figure 16-7: 

Agile 
Agenda 
allows you 
to manage 
your 
projects. 
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For the Niche Croutd: RichFLV 

www. richapps . de/ ?p=48 

RichFLV, shown in Figure 16-8, is one of those useful niche apps that, by the 
way, just so happens to be written in AIR. You can use it to edit Flash Video 
(FLV) files, such as modify metadata, edit cuepoints, and trim down videos. 
RichFLV also allows you to convert FLV files into different formats, including 
SWF, audio MP3, or a JPG image. 

Yes, RichFLV could have been written as a native app, but the fact that it was 
written in AIR is a good testimonial to the power of AIR. 
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Figure 16-8: 

RichFLV is a 
handy FLV 
editing tool. 




The Coat Factor: Snackr 



http : / / snackr . net 

Snackr (see Figure 16-9) is an RSS aggregator that continuously displays 
newsfeed entries as a scrolling ticker on your desktop. If you see a story 
that looks interesting, you can click it and Snackr displays the full story in a 
pop-up window. 

You can dock Snackr to one of the edges of your screen — top, left, right, 
bottom — and can tweak the speed of the scrolling. You can also import 
feeds from another reader using an OPML file or simply paste a new feed 
address into its dialog box. 

Snackr's main selling point is its simple yet slick UI. It just looks cool docked 
to your desktop. However, in terms of overall RSS reading functionality, 
Snackr is bare bones. Clearly, Snackr is not meant as a replacement to a full- 
featured RSS reader, such as Google Reader or NetNewsWire. 



Snackr is one of those apps that you'll probably either love or hate. 
When I first tried it docked to the top of the desktop, I found it completely 
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distracting. However, when I slowed the scroll and moved it to the right side, 
it actually started to grow on me. 



Figure 16-9: 

Snackr dis- 
plays RSS 
entries as a 
ticker. 



If nothing else, Snackr provides a great example of a well-designed RIA that 
solves a problem in a way that a Web app alone can't do. 




The developer, Narciso Jaramillo, wrote the app in Adobe Flex and has 
a write-up about his development approach at www . rictus . com/ 
muchado/2 008/ 05/12 /snackr-an-rss-ticker-built-using-air- 
and- f lex. 



For the Geek Croutd: Snippety 

http : / / code . google . com/p/snippely 

Snippely is a rather nifty utility you can use to organize source code and 
random text snippets. It uses a simple method of organizing snippets into 
distinct categories. Each snippet has a title, optional description, and one or 
more snippets. When you're working with source code, you can specify the 
language, which Snippely then uses to provide syntax highlighting. 

Snippely is a handy way for me to get rid of countless . txt files all over my 
hard drive in which I store a script, CSS style, or serial number for my software. 
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Figure 16-10 shows the Snippely user interface. 




Figure 16-10: 

Snippely 
looks just 
like a Mac 
OSXapp. 
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Basic Default Body Font 

Used on wbythebike.com 



Snippely is written in HTML and JavaScript and stores data locally using AIR's 
SQLite database. 



Groundbreaking Look and Feel: utfLayer 

www . uvlayer . com/download 

uvLayer, shown in Figure 16-11, is a social video application for discovering 
videos, sharing video media with friends, and organizing your own online 
video content. What is immediately striking about uvLayer is its innovative 
drag-and-drop desktop canvas, using tiles as a primary UI metaphor. 

You can search for media across multiple sources and then add them to your 
desktop canvas. Search results are displayed as tiles. You can fan them out 
over your desktop or create stacks of videos. 

You can share videos you collect with your friends through Facebook, Google 
Talk, or AIM, simply by dragging the video on top of the user's icon. 
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Figure 16-11: 

uvLayer 
sports an 
innovative 
futuristic Ul 
metaphor. 
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runtime (continued) 
overview, 8-10 

SDK 

ADT utility, 35-36 
installing, 17-19 
windows 
categories of, 101-102 
display states, 59 
HTML, creating, 112-114 
initial, creating, 58-59, 102-106 
initialization, 59, 112 
mx: Window, creating, 114-115 
native OS, 58-59 

NativeWindow, creating, 115-119 
nonrectangular, Flex, 124-128 
nonrectangular, HTML, 120-124 
properties of, 102-104 
resizing, 60 

system chrome, 59, 106-108 

transparency, 108-110 

type property, 60, 110-112 
Adobe Flash Player, 10 
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dialog box (Flash), 53-54 
AIR Debug Launcher (ADL) utility, 304 
.air files, 9, 37-38 
AIR HTML Introspector, 310-311 
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[air . ] BitmapData class, 63 
[air . ] Camera class, 66 
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[air. ] ClipboardFormats class, 64 
[air . ] ClipboardTransf erMode 

class, 64 
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[air . ] File class, 60-61 
[air . ] FileFilter class, 60-61 
[air . ] FileMode class, 60-61 
[air . ] FileStream class, 60-61 
[air . ] icon class, 63 
[air . ] lD3lnfo class, 65, 276 
[air . ] Interactivelcon class, 63 
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[air . ] KeyLocation class, 67 
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[air . ] Microphone class, 66, 276 
[air . ] Mouse class, 67 
[air . ] NativeDragActions class, 65 
[air . ] NativeDragManager class, 65 
[air . ] NativeDragOptions class, 65 
[air. ] NativeMenu class, 63 
[air . ] NativeMenuItem class, 63 
[air . ] NativeWindow class, 59 
[air. ] NativeWindowDisplayState 
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class, 59 
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[air. ] NativeWindowWindowType 
class, 60 
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[air . ] NetStream class, 72 

[air . ] Notif icationType class, 63 

[air . ] ObjectEncoding class, 72 

[air . ] Responder class, 72 

[air . ] Screen class, 63 

[air. ] SharedObject class, 73 

[air . ] SharedObj ectFlushStatus 

class, 73 
[air . ] Socket class, 72 
[air . ] Sound class, 66, 276 
[air . ] SoundChannel class, 66, 276 
[air. ] SoundLoaderContext class, 

66, 276 

[air . ] SoundMixer class, 66, 276 
[air . ] SoundTransf orm class, 66, 276 
[air . ] SQLCollationType class, 69 
[air . ] SQLColumnNameStyle class, 69 
[air . ] SQLColumnSchema class, 69 
[air . ] SQLConnection class, 69 
[air . ] SQLError class, 69 
[air . ] SQLErrorEvent class, 69 
[air . ] SQLErrorOperation class, 69 
[air . ] SQLEvent class, 69 
[air . ] SQLIndexSchema class, 69 
[air . ] SQLMode class, 69 
[air . ] SQLResult class, 70 
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[air . ] SQLSchema class, 70 
[ai r . ] SQLSchemaResult class, 70 
=nt class, 70 
phema class, 70 
[air . ] SQLTransactionLockType 
class, 70 

[air . ] SQLTriggerSchema class, 70 
[air. ] SQLUpdateEvent class, 70 
[air . ] SQLViewSchema class, 70 
[air . ] SystemTraylcon class, 63 
[air . ] URLLoader class, 70-73 
[air. ] URLLoaderDataFormat class, 71 
[air. ]URLReguest class, 71 
[air. ] URLReguestDef aults class, 71 
[air. ] URLReguestHeader class, 71 
[air . ] URLReguestMethod class, 71 
[air . ] URLStream class, 71 
[air . ] URLVariables class, 72 
[air. ] Video class, 66 
[air. ]XMLSocket class, 72 
AIRAliases . j s file, 57, 213 
AlRBadge . as file, 289 
AlRLogger, 309 
AIRUpdates.html file, 296 
AIRUpdates.mxml file, 297-298 
airversion parameter, 287 
AIRWrite app, 170-179 
AIRWrite text editor 

AIRAliases . js file, 213 

drag-and-drop support, adding, 220-225 

files 

opening asynchronously, 214-215 
saving asynchronously, 215-216 
root menus, 213-214 
user interface, 212-213 
AIRWriteHtml.html file, 216-220 
Ajax, 11 

alert command, 306-307 
aliased objects, 57 
alpha blending, 103, 108 
alpha values, 84-86 
Analytics Reporting Suite, 8 
AOL Music - Top 100 Videos media player, 
318-319 

API (application programming interface) 
calling 
from ActionScript, 58 
from JavaScript, 57 
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database, 68-70 

inter-application data exchange, 64-65 
keyboard, 66-67 
local files, 60-61 
menus, 61-64 
mouse, 66-67 
multimedia, 65-66 
native OS windows, 58-60 
overview, 9 
syntax, 57 
app: scheme, 194 

application communication classes, 73 
application descriptor file, 32-35, 45-46 
application directory, 196 
application element, 33 
application folder, 22 
application ID, 41, 53 
application menu, 130, 140 
application programming interface (API) 

calling 
from ActionScript, 58 
from JavaScript, 57 

communication, 70-73 

database, 68-70 

inter-application data exchange, 64-65 
keyboard, 66-67 
local files, 60-61 
menus, 61-64 
mouse, 66-67 
multimedia, 65-66 
native OS windows, 58-60 
overview, 9 
syntax, 57 
application root directory URL, 195 
Application Setup dialog box, 289 
application storage directory, 195, 197 
application©, 195 
applications, Adobe AIR 
auto-updating, 289-299 
building with Flash CS4 
ActionScript code, adding, 50-52 
application ID, 53 
compiling, 53-54 
configuring, 53-54 
overview, 39 

user interface, designing, 49-50 
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building with Flex Builder 3.0 

creating project, 40-42 
descriptor file, 45-46 
location of project, 40 
MXML, 42-44 
naming projects, 40-41 
preparing for deployment, 47-49 
testing, 46 
building with HTML and JavaScript 
application folder, 22 
descriptor file, 32-35 
HTML-based user interface, 23-24 
installer file, generating, 37-38 
JavaScript code, adding, 27-32 
overview, 21 

self-signed certificate, 36-37 
styles, adding, 25-27 
testing with ADT, 35-36 

digital signature, 14-15 

installing with badge . swf , 286-289 

overview, 8-9 

security, 11-14 

Web technologies in, 11 
ApplicationUpdaterUl instance, 

292, 295 
application . xml file, 32-33 
appname parameter, 287 
appProperties object, 143-144 
app-storage : scheme, 194 
appurl parameter, 287 
Aptana Studio, 304-306 
ArrayCol lection object, 269 
asynchronous connections, 235 
audio files 

microphone, accessing, 283-284 

pausing playback, 279-281 

playing, 276-279 

resuming playback, 279-281 

sound effects, adding, 281-283 
auto-updating 

AIR Update Framework, 290-291 

AIRUpdates.html file, 296 

AIRUpdates.mxml file, 297-298 

checking for updates, 300 



download progress, 300 
installing updates, 300 
overview, 289-290 
release notes, 299 

source code, adding update to, 292-295 
updater descriptor file, 291 



backupFolder variable, 60-61 
badge, f la file, 289 
badge . swf installer 

benefits of, 286 

f lashvars parameters, 287 

helper text, 287 

setting up, 286-289 

source files, 289 
beginPath() method, 88 
bind ( ) method, 29 
Bitmap class, 63 
bitmap format, 164 
BitmapData class, 63, 167 
bitmaps property, 146 
BOOLEAN data type, 234 
browseForDirectory ( ) method, 199 
browseForOpen ( ) method, 

200-202, 214 
browseForOpenMultiple ( ) method, 
203-206 

browseForSave ( ) method, 202 
bubbling phase, 99 
buttoncolor parameter, 287 
ByteArrayO method, 210-211 



Camera class, 66 
canvas element 

adding, 86-87 

color, 91 

context object, 87 

nonrectangular shapes, drawing, 88-89 

overview, 86 

rectangles, drawing, 87 

transparency, 91 
Icanvas rule, 25 
capture phase, 99 
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styles, adding with, 25-27 
81-82 
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creating 
in Flash CS4, 54 
in Flex Builder, 47-49 
overview, 36-37 
overview, 14-15 
Check for Updates dialog box, 299 
Chinese text, linebreak rule for, 81 
chrome. See also windows 
custom, 107-108 
Flex, 108 
standard, 107 
CirculAIR.mxml file, 126-128 
classes 
application communication 
Local Connection, 73 
NetConnection, 73 
SharedObject, 73 
SharedObjectFlushStatus, 73 
clipboard 
Clipboard, 64 
ClipboardFormats, 64 
ClipboardTransf erMode, 64 
database 
EncryptedLocalStore, 68 
SQLCollationType, 69 
SQLColumnNameStyle, 69 
SQLColumnSchema, 69 
SQLConnection, 69 
SQLError, 69 
SQLErrorEvent, 69 
SQLErrorOperation, 69 
SQLEvent, 69 
SQLIndexSchema, 69 
SQLMode, 69 
SQLResult, 70 
SQLSchema, 70 
SQLSchemaResult, 70 
SQLStatement, 70 
SQLTableSchema, 70 
SQLTransactionLockType, 70 
SQLTriggerSchema, 70 
SQLUpdateEvent, 70 
SQLViewSchema, 70 
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File, 60-61, 194 

FileFilter, 60-61 

FileMode, 60-61, 194 

FileStream, 60-61, 194, 210-211 

identifying, 193-194 
media 

Camera, 66 
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Microphone, 66 

Sound, 66 

SoundChannel, 66 

SoundLoaderContext, 66 

SoundMixer, 66 

SoundTransf orm, 66 

Video, 66 
network connection 

NetStream, 72 

Obj ectEncoding, 72 

Responder, 72 

Socket, 72 

URLLoader, 71 

URLLoaderDataFormat, 71 

URLRequest, 71 

URLRequestDef aults, 71 

URLRequestHeader, 71 

URLReguestMethod, 71 

URLStream, 71 

URLVariables, 72 

XMLSocket, 72 
user interface 

Bitmap, 63 

BitmapData, 63 

Docklcon, 63 

Icon, 63 

Interactivelcon, 63 
Loader, 63 
NativeMenu, 63 
NativeMenultem, 63 
Notif icationType, 63 
Screen, 63 
SystemTraylcon, 63 
window 
NativeMenu, 63 
NativeWindow, 59 
NativeWindowDisplayState, 59 
NativeWindowInitOptions, 59 
NativeWindowResize, 60 
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window (continued) 
NativeWindowSystemChrome, 59 
j-ndowType, 60 
63 

ear() method, 164-165 
Clipboard. See also drag-and-drop support 
classes, 64-65 
formats, 164 

in HTML environments, 166 
images 

copying, 167 

pasting, 167-169 
overview, 163-164 
pasting text from, 165-166 
text 

copying to, 164-165 
cutting to, 165 
Clipboard class, 64-65 
ClipboardFormats class, 64 
ClipboardTransf erMode class, 64 
close ( ) method, 28-30 
Close command, 29 
closeApp ( ) function, 43 
closeHandler ( ) function, 51 
closePathO method, 88 
code-signed certificates, 14-15 
commercial certificates, 15 
conf igObject array, 313 
CONNECT event, 270 
connectDatabase ( ) function, 253 
connectToServer ( ) function, 270 
content element, 34 
content property, 102 
context menu 

denned, 140 

description of, 130 

in Flex, 141 

in HTML, 140-141 

versus pop-up menu, 132 
context object, 87, 90 
ContextMenu class, 141 
ContextMenul tern class, 141 
copyright element, 33 
copyTo ( ) method, 61, 207-209 
copyToAsync ( ) method, 207-209 
Create Project Wizard (Flex Builder), 40-42 
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Flash, 54 

Flex Builder, 47-49 
CREATE TABLE statement (SQL), 233-235 
createDirectory ( ) method, 206 
createFileMenu ( ) function, 213 
createMenuCommand ( ) function, 214 
createMenuSeparator ( ) 

function, 214 
createTempDirectory ( ) method, 207 
createTempFile ( ) method, 207 
CSS (Cascading Style Sheets) 

styles, adding with, 25-27 

WebKit extensions, 81-82 
custom chrome, 107-108 
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data types, 234-235 
database 
connections 

asynchronous, 235 

opening to, 235-237 

synchronous, 235 
data types, 234-235 
encrypted local store, 68 
local, 227-228 
records 

adding, 232 

adding conditions on, 230-231 

deleting, 233 

inserting, 240-251 

retrieving from tables, 232 

updating, 232 
sort order, 231-232 
tables 

creating in, 233, 238-239 
requesting data from, 251-256 
retrieving records from, 229-230 
database classes 

EncryptedLocalStore, 68 
SQLCollationType, 69 
SQLColumnNameStyle, 69 
SQLColumnSchema, 69 
SQLConnection, 69 
SQLError, 69 
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SQLErrorEvent, 69 
SQLErrorOperation, 69 
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SQLMode, 69 



SQLResult, 70 

SQLSchema, 70 

SQLSchemaResult, 70 

SQLStatement, 70 

SQLTableSchema, 70 

SQLTransactionLockType, 70 

SQLTriggerSchema, 70 

SQLUpdateEvent, 70 

SQLViewSchema, 70 
DataDisplay.html, 254-256 
DATE data type, 234 
debugging 

AIR Debug Launcher, 304 

AIR HTML Introspector, 310-311 

AIRLogger, 309 

alert command, 306-307 

Aptana Studio, 304-306 

debug window, creating, 308-309 

description of, 303 

Flex Builder, 312 

multiple platforms, 312 

source code, viewing, 312-313 

trace method, 307-308 
default behaviors, 97-98 
delay property, 292 
deleteFileO method, 209 
deleteFileAsync ( ) method, 209 
description element, 33 
descriptor file, 32-35, 45-46 
desktop directory, 197 
digital signature 

creating 
in Flash CS4, 54 
in Flex Builder, 47-49 
overview, 36-37 

overview, 14-15 
Digital Signature dialog box (Flash), 54 
directories 

application, 196 

application storage, 195, 197 

choosing, 199-201 

copying, 207-209 



creating, 206 
deleting, 209 
desktop, 197 
document, 197 
file system root, 197 
home, 197 
moving, 207-209 
paths, 61 

pointing to, 196-198 
root, 195 

temporary, 197, 207 

user's desktop, 197 

user's document, 197 

user's home, 197 
disconnectFromServer ( ) 

function, 271 
displaying event, 132 
div element, 23 
dock icon menu, 131 
Dockicon class, 63 
document directory, 197 
document .write ( ) component, 13 
Download Progress dialog box, 300 
downloading 

Adobe AIR runtime, 16 

Adobe AIR SDK, 17 

updates 

AIR Update Framework, 290-291 
AIRUpdates.html file, 296 
AIRUpdates.mxml file, 297-298 
checking for updates, 300 
download progress, 300 
installing updates, 300 
overview, 289-290 
release notes, 299 

source code, adding update to, 292-295 

updater descriptor file, 291 
drag-and-drop support 
adding 

in Flash, 170-181 

in Flex, 170-181 

in HTML, 181-191 
drag initiator, 169 
draggable elements, 183-185 
drop target, 169, 186-187 
sequence in, 169 
dragdropme.html file, 189-191 
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draggable elements, 183-185 
draginit-div element, 183-184 
gment, 183 

dropFeed ( ) function, 245 



eBay Desktop, 317-318 
Eclipse IDE, 263 

editCopyO command, 164-165 
EncryptedLocalStore class, 68 
environment path 
Windows Vista, 17-18 
Windows XP, 18 
eval ( ) component, 13 
event handling, 94-95 
event listener, 94 
event objects, 95-97 
events 
bubbling phase, 99 
capture phase, 99 
flow, 98-100 
registering, 95 
responding to, 93-94 
target phase, 99 
exit ( ) method, 30 
EXITING event, 271 
Export Release Build dialog box (Flex 

Builder), 47 
extensions, WebKit 
-webkit-appearance, 83-84 
-webkit-background-size, 24, 81 
-webkit -border-bottom- left- 
radius, 81 
-webki t -border-bo t torn- right - 

radius, 81 
- webki t-border-horiz ontal- 

spacing, 81 
-webkit-border-radius, 22, 26-27, 

81, 82-83 
-webki t-border- top- left- 
radius, 81 
- webki t-border- top- right - 

radius, 81 
-webki t-border- vertical - 
spacing, 81 



-webkit-line-break, 81 
-webkit -margin-bottom- 
collapse, 81 
-webkit-margin-collapse, 82 
-webkit-margin-start, 82 
-webkit-margin-top-collapse, 82 
-webkit-nbsp-mode, 82 
-webkit-padding-start, 82 
-webkit-rtl-ordering, 82 
-webkit-text-f ill-color, 82 
-webkit-text-security, 82 
-webkit-user-drag, 82, 181 
-webkit-user-modify, 82 
-webkit-user-select, 82 



FaultEvent event, 96 
File class, 60-61, 194 
file classes 

File, 60-61, 194 

FileFilter, 60-61 

FileMode, 60-61, 194 

FileStream, 60-61, 194, 210-211 

identifying, 193-194 
file list format, 164 
File Open dialog box, 200-202 
File Save dialog box, 200-202 
file: / // scheme, 194 
file system directories 

application, 196 

application storage, 195, 197 

file system root, 197 

pointing to, 196-198 

root, 195, 197 

temporary, 197 

user's desktop, 197 

user's document, 197 

user's home, 197 
file URLs, 195 

File . browseForDirectory ( ) method, 
199 

File .browseForOpen ( ) method, 200- 
202 

File .browseForOpenMultiple ( ) 
method, 203-206 
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r xxtj . uupy i u \ ) men 

DropSOSt^ 

method. 209 



File .browseForSave ( ) method, 202 
File . copyTo ( ) method, 207-209 
method, 209 
_b.sync ( ) 

method, 209 
FileFilter class, 60-61 
FileMode class, 60-61, 194 
f ileMode parameter, 210-211 
File.moveToO method, 207-209 
File .moveToTrash ( ) method, 209 
File . moveToTrashAsync ( ) 

method, 209 
filename element, 33 
fileNewO function, 142 
f ileOpen( ) function, 61-64 
Filer.mxml file, 204-206 
files 
audio 

microphone, accessing, 283-284 

pausing playback, 279-281 

playing, 276-279 

resuming playback, 279-281 

sound effects, adding, 281-283 
copying, 207-209 
creating temporary, 207 
displaying multiple, 203-206 
filtering, 61 
icon, 34 
local, 60-61 
modes, 210 
moving, 207-209 
MP3, 65 

opening, 61, 200-202 
paths, 61 

pointing to, 198-199 
reading, 210-211 
writing to, 211-212 

f ileSaveAs ( ) function, 216 

FileStream class, 60-61, 194, 210-211 

fillO method, 88 

fillRect ( ) method, 87 

FillStyle property, 90 

Flash CS3, 19-20 

Flash CS4 
ActionScript code, adding, 50-52 
building applications with, 49-54 
configuring and compiling, 53-54 



drag-and-drop support, adding, 167-169 
user interface, designing, 49-50 

Flash media, 1 1 

Flash Player, 10 

f lashvars parameter, 287 

Flex, 11 

Flex Builder 3.0 
ActionScript, 42-44 
building applications with, 39-49 
creating project, 40-42 
debugging with, 312 
description of, 39 
descriptor file, 45-46 
drag-and-drop support, adding, 170-181 
MXML, 42-44 

naming applications, 40-41 

preparing for deployment, 47-49 

project, creating, 40-42 

testing, 46 
Flex chrome, 108 
FlexAir.mxml file, 116-119 
FlexNativeMenu instance, 144 
folder, application, 22 
Function constructor, 13 

• G • 

getContext ( ) method, 86 
getData ( ) method, 187 
getHistoryAt ( ) member, 80 
getMicrophone ( ) function, 283-284 
GlobalAlpha property, 90 
GlobalCompositeOperation 

property, 90 
Google, detecting connectivity to, 259 
Google Analytics Reporting Suite, 316-317 



hi tag, 24-25 

hasFormat ( ) method, 167 
head element, 23 
height property, 104 
historyBack ( ) member, 80 
historyForward ( ) member, 80 
HistoryLength ( ) member, 80 
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HistoryPosition ( ) member, 80 
home directory, 197 



nom e directory, iy/ 
CliDboard format, li 



is with, 21-38 
Clipboard format, 164 
context menu, 130, 140-141 
drag-and-drop support, adding, 181-191 
for network service monitoring, 259 
overview, 11 
pop-up menu, 141-142 
windows, 102, 112 
HTMLLoader object, 56 
accessing, 78 

history-related members, 80 
HTML content, loading, 78-79 
overview, 77 
sizing, 78 

URL, launching in default system 
browser, 79 



icon class, 63 
icon files, 34 
iD3info class, 65, 276 
IF NOT EXISTS clause, 234 
ImageMover.mxml file, 179-181 
imageurl parameter, 287 
init ( ) function, 95, 170 
initialize () method, 28-29, 31 
initialwindow element, 33-34, 102-106 
innerHTML component, 14 
INSERT INTO statement (SQL), 232 
Install Update dialog box, 300 
installer file, generating, 37-38 
INTEGER data type, 234 
Interactivelcon class, 63 
inter-application data exchange, 64-65 
Internet-sawy apps, 9-10 
IO.ERROR event, 270 
isCheckForUpdateVisible property, 
293 

isDirty variable, 214 

isDownloadProgressVisible property, 
293 

isDownloadUpdateVisible property, 
293 



isFileUpdateVisible property, 293 
islnstallUpdateVisible property, 293 
isNewFile variable, 214 



Japanese text, linebreak rule for, 81 
Java apps, 9 
Java For Dummies, 263 
Java SE Developer's Kit, 263 
JavaScript 
audio 

pausing playback, 279-281 
playing, 65 

resuming playback, 279-281 
building applications with, 21-38 
calling AIR API from, 57 
canvas, defining, 86 
connecting to database, 68 
connectivity, detecting, 260 
database record, inserting, 240 
debugging, 306 
directories 

copying, 207-208 

copying to another location, 60 

creating, 206 

creating temporary, 207 
displaying 

Choose Directory dialog box, 199-200 

File Save dialog box, 202 

Select Directory dialog box, 199, 201 

Select Multiple Files dialog box, 203-204 
files 

copying, 207-208 

creating temporary, 207 

writing to, 211-212 
keyboard input, 67 
menu commands 

creating, 134 

selecting handlers for, 141-142 
menus 

application, 140 

attaching objects to, 139 

updating, 143-144 

window, 139-140 
microphone, accessing, 283 
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overview, 11 
reading file, 211 
~^ta^le^o1~a*viNg, 87 
g>|j^yi Jfe&g, 133 

socket connection, 266 
sound effects, 281-283 
submenus, creating, 133 
text 

copying to clipboard, 64 
copying to desktop, 60 
pasting from clipboard, 165-166 
window through API, creating, 58-59 
Jot 

descriptor file, 27-32 

folder, preparing, 22 

HTML-based user interface, 23-24 

installer file, generating, 37-38 

JavaScript code, adding, 27-32 

styles, adding, 25-27 

testing with ADT utility, 35-37 



• K • 



keyboard 
accessing, 66-67 
key location, 67 

mnemonic key assignments, 137-138 

user interaction classes, 67 
Keyboard class, 67 
keyEquivalent property, 136-137 
KeyLocation class, 67 
Korean text, linebreak rule for, 81 
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Lierman, Nicholas, 316 
Lightweight window, 1 10-1 1 1 
LineCap property, 90 
LineJoin property, 90 
lineTo (x,y) method, 88 
lineWidth property, 90 
link reference, 23 
links, 83-84 
load( ) method, 78 
Loader class, 63 
loadString ( ) method, 78 



Local Connection class, 73 
local databases, 227-228 
local files, 60-61 
log() method, 310 
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Mac OS X 

enabling apps for dock, 146 

setting system path in, 18-19 
maximizable property, 103, 112 
maxSize property, 104 
media classes 

Camera, 66 

lD3lnfo, 65 

Microphone, 66 

Sound, 66 

SoundChannel, 66 

SoundLoaderContext, 66 

SoundMixer, 66 

SoundTransf orm, 66 

Video, 66 
menu items 

attaching objects to, 139 

deselecting, 138 

disabling, 138-139 

enabling, 138-139 

selecting, 138 
MenuAIR 

Dock icon, 159 

File menu items, 159 

Flex version, 152-157 

HTML version, 147-151 

pop-up menu, 160 

Search menu item, 160 

Tool tip, 160 

View menu, 160 
menus 

Adobe AIR API, 61-64 

application, 130, 140 

classes, 63 

commands, 134-135 

creating, 61-62, 131-132 

dock icon, 131 

HTML/SWF context, 130 

mnemonic key assigments, 137-138 
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menus (continued) 
modifier keys, setting, 137 

Lex^fJ^Ti^lenu, 131 

primary key, setting, 136-137 
root, 132-133 
selecting events, 142-143 
separators, 135-136 
submenus, 133-134 
system tray icon, 130 
types of, 130-131 
updating, 143-144 
window, 130, 139-140 
messagecolor parameter, 287 
microphone, 283-284 
Microphone class, 66, 276 
Microsoft Windows Vista, 17-18 
Microsoft Windows XP, 18 
minimizable property, 103, 112 
minimumPatchLevel attribute, 33 
minSize property, 104 
miterLimit property, 90 
mnemonic keys, assigning, 137-138 
modifier keys, 137 
mouse, 66-67 
Mouse class, 67 
moveTo ( ) method, 207-209 
moveTo (x,y) method, 88 
movetoAsync ( ) method, 207-209 
moveToTrash ( ) method, 209 
moveToTrashAsync ( ) method, 209 
MP3 files, 65 
multimedia classes 
Camera, 66 
ID3lnf o, 65 
Microphone, 66 
Sound, 66 
SoundChannel, 66 
SoundLoaderContext, 66 
SoundMixer, 66 
SoundTransf orm, 66 
Video, 66 
multiple platforms, testing on, 312-313 
mx : Button element, 43 
mx:Flex Nat iveMenu menu, 131 



MXML 

adding, 42-44 

layout, 241 
mx: Script element, 43 
mx : Window element 

creating, 114-115 

nonrectangular, 124-128 

overview, 102 
mx: WindowedApplication element, 
42-43 



native OS windows, creating, 58-60 
native paths, 194 

NativeApplication class, 30, 43-44 
NativeDragActions class, 65 
NativeDragEvent class, 96-97 
NativeDragManager class, 65, 170 
NativeDragOptions class, 65 
NativeMenu class, 63, 131-132 
Nat iveMenu I tern class, 63, 131-132 
nativepath property, 194 
NativeWindow class, 56, 59 
NativeWindowDisplayState class, 59 
NativeWindowInitOptions ( ) 

object, 59 
NativeWindowResize class, 60 
NativeWindowSystemChrome class, 59 
NativeWindowWindowType class, 60 
navigateToURL ( ) function, 72 
NetConnection class, 73 
NetStream class, 72 
network connection classes 

NetStream, 72 

Obj ectEncoding, 72 

Responder, 72 

Socket, 72 

URLLoader, 71 

URLLoaderDataFormat, 71 

URLReguest, 71 

URLReguestDef aults, 71 

URLReguestHeader, 71 

URLReguestMethod, 71 

URLStream, 71 

URLVariables, 72 

XMLSocket, 72 
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network connectivity 
detecting, 257-258 

Drop [$tete ce monl,or "' s ' 259 

socket connections, 261-262 
NETWORK_CHANGE event, 258-259 
New Flex Project dialog box (Flex 

Builder), 40 
NONE data type, 234 
nonrectangular shapes, creating, 88-89 
nonrectangular windows 

creating, 120-128 

in Flex, 124-128 

in HTML, 120-124 
Normal window, 110-1 1 1 
Notif icationType class, 63 
NUMBER data type, 234 
NUMERIC data type, 234 

•0 • 

OBJECT data type, 234 
ObjectEncoding class, 72 
onConnect ( ) handler, 270 
oncontextmenu event, 140 
onDataReceived ( ) function, 270 
onDragDrop ( ) function, 97, 171, 245 
onDragEnter ( ) function, 187 
ondragenter event, 186 
onDraginO function, 96-97, 170, 176 
onDragOver ( ) function, 187 
ondragover event, 186 
ondrop event, 186 
onFetchComplete ( ) function, 245 
onFileSaveAsSelect ( ) function, 216 
onFileSelect ( ) function, 172, 214 
onmousedown event, 29 
onMouseMove ( ) function, 178 
onSelectResult ( ) function, 253 
openAsync ( ) function, 214 
ORDER BY command (SQL), 231-232 



password, 37 
paths 

app: scheme, 195 

app-storage: scheme, 195 



file: / // scheme, 195 

nativePath property, 194 

url property, 194 
playSound ( ) function, 276-278, 282 
poll Interval property, 259 
pop-up menu, 130, 132, 141-142 
pre-defined file system directories 

application, 196 

application storage, 195, 197 

file system root, 197 

pointing to, 196-198 

root, 195 

temporary, 197 

user's desktop, 197 

user's document, 197 

user's home, 197 
preventDef ault ( ) method, 97-98, 141 
primary key, setting, 136-137 
Properties inspector (Flash), 49 
publisherlD, 195 
push buttons, 83-84 

•Q • 

Quit command (Mac OS x), 29 



readBytesO method, 210-211 
readMultiByte ( ) method, 210-211 
readUTFO method, 210-21 1 
readUTFBytes ( ) method, 210-211 
REAL data type, 234 

ReallySimpleServer . java file, 263-265 
rectangles, drawing, 87 
refreshSizeO method, 28, 30-31 
release notes, 299 
remote network services 
detecting, 257-258 

HTML apps for service monitoring, 259 

monitoring, 258-261 

socket connections, 261-262 
resizable property, 103, 112 
resolvePath ( ) method, 

30, 60, 198-199, 236 
Responder class, 72 
reverse domain format, 33 
reverse domain name, 41, 53 
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rgba ( ) declaration, 84, 91 
RIAs (rich Internet applications) 

1 HsJfV^SPO Videos. 318-319 
eBay Desktop, 317-318 
Google Analytics Reporting Suite, 316-317 
overview, 7 
RichFLV, 321-322 
Snackr, 322-323 
Snippely, 323-324 
Snitter, 319-320 
twhirl, 319-320 
uvLayer, 324-325 
Rich Text Format (RTF), 164 
RichFLV, 321-322 
root menu, 132-133 

rootMenuNativeMenu instance, 61-64 

rounded rectangles, creating, 82-83 

rssdrop.mxml file, 246-251 

rssf eed folder, 236 

RTF (Rich Text Format), 164 

runtime object, 57 



sandboxes 

JavaScript activities, 13-14 

overview, 12 

restrictions, 12-14 
save ( ) method, 28-30 
saveApp ( ) function, 43 
saveHandler ( ) function, 51 
Screen class, 63 
script tag, 23 

SecondWindow.mxml file, 114-115 
SELECT command (SQL), 229-230 
Select Directory dialog box, 199-201 
select event, 132 

Select Multiple Files dialog box, 203-204 
selectDirectory ( ) event handler, 199 
SelectFromDatabase ( ) function, 253 
selectTrapper ( ) function, 142-143 



self-signed certificates 
creating 
in Flash CS4, 54 
in Flex Builder, 47-49 
overview, 36-37 
overview, 14-15 
sendToURL ( ) function, 72 
separators, 135-136 

server push socket connection, 268-273 
service monitoring. See also network 
connectivity 

HTML apps for, 259 

overview, 258-259 

socket connections, 261-262 

Web site connectivity, 259-261 
ServiceMonitor class, 259 
setData ( ) method, 64, 164-165, 

178, 184 
setDraglmage ( ) method, 184 
setlnterval ( ) method, 13 
shadowBlur property, 90 
shadowColor property, 90 
shadowOf f setx property, 90 
shadowOf f setY property, 90 
SharedObject class, 73 
SharedObjectFlushStatus class, 73 
SimplePushServer class, 269 
Snackr, 322-323 
Snippely, 323-324 
Snitter, 319-320 
Socket class, 72 

socket connections. See also network 
connectivity 

ActionScript, 72 

adding, 265-268 

monitoring, 261-262 

overview, 262 

server, 262-265 

server push, 268-273 
SocketMonitor class, 259, 261-262 
SockIt2Me . html file, 267 
Socklt2Me.mxml file, 267-268 
Sound class, 66, 276 
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Drop 



sound files 
microphone, accessing, 283-284 

^0 79-281 

resuming playback, 279-281 
sound effects, adding, 281-283 
SoundChannel class, 66, 276, 279-281 
SoundLoaderContext class, 66, 276 
SoundMixer class, 66, 276 
SoundTransf orm class, 66, 276, 281-283 
source code, viewing, 312-313 
SourceViewer object, 312-313 
SQL (Structured Query Language) 
classes, 68-70 
connections 
asynchronous, 235 
opening, 235-237 
synchronous, 235 
CREATE TABLE statement, 233-235 
data types, 234-235 
INSERT INTO statement, 232 
local, 227-228 

ORDER BY command, 231-232 
overview, 228-229 
records 
adding, 232 

adding conditions on, 230-231 

deleting, 233 

inserting, 240-251 

retrieving from tables, 229-230 

updating, 232 
SELECT command, 229-230 
sort order, 231-232 
tables 

creating, 233, 238-239 

requesting data from, 251-256 

retrieving records from, 229-230 
unsupported features in AIR, 233 
UPDATE statement, 232 
WHERE command, 230-231 
SQL For Dummies, 228 
SQL statement 
creating database tables, 238-239 
inserting records, 240-251 
requesting data from tables, 251-256 
SQLCollationType class, 69 



SQLColumnNameStyle class, 69 
SQLColumnSchema class, 69 
SQLConnection class, 69 
SQLError class, 69 
SQLErrorEvent class, 69 
SQLErrorOperation class, 69 
SQLEvent class, 69 
SQLlndexSchema class, 69 
SQLite, 10, 68, 228 
SQLMode class, 69 
SQLResult class, 70 
SQLSchema class, 70 
SQLSchemaResult class, 70 
SQLStatement class, 70 
SQLTableSchema class, 70 
SQLTransactionLockType class, 70 
SQLTriggerSchema class, 70 
SQLUpdateEvent class, 70 
SQLViewSchema class, 70 
stageClickHandler ( ) method, 100 
standard chrome, 107 
start ( ) method, 259 
startMove ( ) method, 29 
StatusEvent instance, 261 
stroke ( ) method, 88 
strokeRect ( ) method, 87 
StrokeStyle property, 90 
Structured Query Language (SQL) 

classes, 68-70 

connections 
asynchronous, 235 
opening, 235-237 
synchronous, 235 

CREATE TABLE statement, 233-235 

data types, 234-235 

INSERT INTO statement, 232 

local, 227-228 

ORDER BY command, 231-232 
overview, 228-229 
records 
adding, 232 

adding conditions on, 230-231 
deleting, 233 
inserting, 240-251 
retrieving from tables, 229-230 
updating, 232 
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Structured Query Language (continued) 
SELECT command, 229-230 




creating, 233, 238-239 
requesting data from, 251-256 
retrieving records from, 229-230 
unsupported features in AIR, 233 
UPDATE statement, 232 
WHERE command, 230-231 
stylesheets. See CSS 
submenus, 133-134 
submitNowO function, 94 
subscribe ( ) function, 270 
SWF context menu, 130 
synchronous connections, 235 
system chrome 
custom, 107-108 
Flex, 108 

overview, 106-107 

standard, 107 
system path, Mac OS X, 18-19 
system tray 

enabling apps for, 145-146 

icon menu, 130 
systemChrome property, 34, 45, 103, 112 
SystemTraylcon class, 63 

• r» 

taEditor ID, 49-50 
talkToMe ( ) method, 73 
target phase, 99 
taskbar, 145 

TCP/IP socket connection, 262 
temporary directory, 197, 207 
Test Movie (Flash), 52 
testcert . pl2 file, 37-38 
text 
copying 
to clipboard, 64, 165 
to desktop, 60 
cutting, 165 
pasting 
from clipboard, 165-166 
into text memo, 166 



TEXT data type, 234 
text format, 164 

textarea element, 24, 25-26, 49-50, 98 

textClickHandler ( ) method, 100 

Thawte, 15 

Timeline (Flash), 50 

title property, 103 

trace method, 307-308 

transparency, 108-110 

transparent property, 46, 103, 112 

twhirl, 319-320 

Twitter, 319 

2D context object, 87 

TwoSocks.mxml file, 272-273 

Type property, 112 

• U • 

UNIQUE operator, 243 
Update Available dialog box, 299 
UPDATE statement (SQL), 232 
updater, application 

adding to source code, 292-295 

AIRUpdates.html file, 296 

AIRUpdates.mxml file, 297-298 

ApplicationUpdaterUl instance, 
292, 295 

checking for updates, 295, 299 

customizing from code, 292-294 

descriptor file, 291-292 

downloading updates, 300 

event handlers, 295 

installing updates, 300 

XML configuration file, 294 
updateURL property, 292 
URL 

launching in default system browser, 79 
network connection classes, 71-72 

URL format, 164 

url property, 194 

URLLoader class, 71 

URLLoaderDataFormat class, 71 

URLMonitor class, 259-261 

URLRequest class, 71 

URLRequestDef aults class, 71 

URLRequestHeader class, 71 
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URLRequestMethod class, 71 
URLS tream class, 71 

D TO O ^^ O^I^r^ter. 99 

user interaction classes, 67 
user interface 
classes, 63 

Flash-based Air apps, 49-50 

HTML-based, 23-24 
user's desktop directory, 197 
user's document directory, 197 
user's home directory, 197 
Utility window, 110-111 
uvLayer, 324-325 

.(/. 

Verisign, 15 
version element, 33 
video class, 66 

viewSourceO method, 312-313 
visible property, 34, 103 

• W 

W3C DOM Level 2 event model, 95 
Web applications 

AgileAgenda, 321 

AOL Music - Top 100 Videos, 318-319 

eBay Desktop, 317-318 

Google Analytics Reporting Suite, 316-317 

overview, 7 

RichFLV, 321-322 

Snackr, 322-323 

Snippely, 323-324 

Snitter, 319-320 

twhirl, 319-320 

uvLayer, 324-325 
Web sites 

Adobe AIR, 16 

AgileAgenda, 32 1 

AIRLogger, 309 

AOL Music - Top 100 Videos, 318-319 
Aptana Studio, 306 
eBay Desktop, 317-318 



Google Analytics Reporting Suite, 316-317 
RichFLV, 321-322 
Snackr, 322-323 
Snippely, 323-324 
Snitter, 319-320 
SQLite, 10 
twhirl, 319-320 
uvLayer, 324-325 
WebKit, 9-10 
WebKit 
Adobe Flash Player, 10 
creating round rectangles, 82-83 
description of, 81-82 
making links into push buttons, 83-84 
overview, 9-10 
setting alpha values, 84-86 
SQLite, 10 

-webkit-appearance extension, 83-84 
-webki t -background- si ze extension, 
24,81 

-webki t -border-bottom- left- 
radius extension, 81 
- webki t -border -bottom- right - 

radius extension, 81 
- webki t-border-horiz ontal- 

spacing extension, 81 
-webkit-border-radius extension, 

22, 26-27, 81, 82-83 
-webki t -border- top- left- radius 

extension, 81 
- webki t -border- top- right -radius 

extension, 81 
- webki t -border- vertical -spacing 

extension, 81 
-webkit-line-break extension, 81 
-webki t -margin-bottom-col lapse 

extension, 81 
-webki t -margin- col lapse 

extension, 82 
-webkit-margin-start extension, 82 
-webki t-margin- top- col lapse 

extension, 82 
-webkit-nbsp-mode extension, 82 
-webkit-padding-start extension, 82 
-webkit-rtl-ordering extension, 82 
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-webkit- text- fill-color 
extension, 82 
k^tyfeeJ^-sM^urity extension, 82 
\jj\jj\'^^ LC f extension, 82, 181 
-webkit-user-modify extension, 82 
-webkit-user-select extension, 82 
WHERE command (SQL), 230-231 
widgets, 9 

width property, 104 
window classes 

NativeMenu, 63 

NativeWindow, 59 

NativeWindowDisplayState, 59 

NativeWindowInitOptions, 59 

NativeWindowResize, 60 

NativeWindowSystemChrome, 59 

NativeWindowWindowType, 60 

SystemTraylcon, 63 
window closing event, 29 
window menu, 130, 139-140 
window object, 56 
windows 

categories, 101-102 

content, 102 

display states, 59 

height, 104 

HTML, creating, 112-114 
initial, creating, 58-59, 102-106 
initialization options, 59 
initialization properties, 112 
lightweight, 110-111 
maximizing, 103-104 
minimizing, 103-104 
mx: Window, creating, 114-115 
native OS, 58-59 

NativeWindow, creating, 115-119 



nonrectangular 

in Flex, 124-128 

in HTML, 120-124 
normal, 110-111 
properties, 102-104 
resizing, 60, 103 
system chrome, 59, 106-108 
title, 103 

transparency, 103, 108-110 

type property, 60, 110-112 

utility, 110-111 

visible, 103 

width of, 104 
Windows Vista, 17-18 
Windows XP, 18 

writeMultiByte ( ) method, 211-212 

x property, 104 

XHTML document shell, 23 

XML data type, 234 

XML socket connection. See also network 
connectivity 

ActionScript, 72 

adding, 265-268 

overview, 262 

server, 262-265 

server push, 268-273 
XMLHttpRequest object, 13, 310 
XMLLIST data type, 234 
XMLSocket class, 72 

•y- 

y property, 104 
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